hail-hydra-cc 2.0.3 → 2.1.0

package/README.md

@@ -56,18 +56,21 @@ npx hail-hydra-cc --help         # Show help
 │   ├── hydra-coder.md
 │   ├── hydra-analyst.md
 │   └── hydra-sentinel.md
-├── commands/hydra/              # 7 slash commands
+├── commands/hydra/              # 8 slash commands
 │   ├── help.md                  # /hydra:help
 │   ├── status.md                # /hydra:status
 │   ├── update.md                # /hydra:update
 │   ├── config.md                # /hydra:config
 │   ├── guard.md                 # /hydra:guard
 │   ├── quiet.md                 # /hydra:quiet
-│   └── verbose.md               # /hydra:verbose
-├── hooks/                       # 3 lifecycle hooks
+│   ├── verbose.md               # /hydra:verbose
+│   └── report.md                # /hydra:report
+├── hooks/                       # 4 lifecycle hooks
 │   ├── hydra-check-update.js    # SessionStart — version check
 │   ├── hydra-statusline.js      # StatusLine — status bar
-│   └── hydra-auto-guard.js      # PostToolUse — file tracker
+│   ├── hydra-auto-guard.js      # PostToolUse — file tracker
+│   ├── hydra-notify.js          # Notification — task completion sound
+│   └── hydra-task-complete.wav  # Notification sound file
 └── skills/hydra/                # Skill (Claude Code discoverable via /skills)
     ├── SKILL.md                 # Orchestrator instructions
     ├── VERSION                  # Installed version

package/files/SKILL.md

@@ -14,6 +14,49 @@ description: >
 > *"Cut off one head, two more shall take its place."*
 > Except here — every head is doing your work faster and cheaper.
 
+## ⛔ MANDATORY PROTOCOLS — NEVER SKIP
+
+These protocols are NON-NEGOTIABLE. Skipping them is a framework violation.
+
+### Protocol 1: Sentinel Scan After Code Changes
+
+When ANY agent returns output containing `⚠️ HYDRA_SENTINEL_REQUIRED`, you
+MUST — before doing ANYTHING else, before presenting results to the user,
+before running any other agents — dispatch hydra-sentinel-scan with the
+files and changes listed in the trigger block.
+
+**This is blocking.** The user does NOT see the code changes until sentinel
+completes. If you present code changes to the user without running sentinel
+first, you have violated the framework's core safety guarantee.
+
+Sequence:
+1. Receive agent output containing ⚠️ HYDRA_SENTINEL_REQUIRED
+2. IMMEDIATELY dispatch hydra-sentinel-scan AND hydra-guard in parallel
+3. WAIT for both to complete
+4. If sentinel-scan finds issues → dispatch hydra-sentinel (deep analysis)
+5. WAIT for deep analysis
+6. THEN — and ONLY then — present results to the user
+
+If the agent output contains `✅ HYDRA_NO_CODE_CHANGES`, skip sentinel. Present
+results immediately.
+
+### Protocol 2: Sentinel Fix Decision Tree
+
+When hydra-sentinel confirms real issues:
+
+**TRIVIAL** (auto-fix without asking):
+  Import renames, file path updates, barrel file re-exports.
+  → Dispatch hydra-coder to fix. Re-run sentinel-scan to verify.
+  → Tell user: "Sentinel caught [issue]. Auto-fixed."
+
+**MEDIUM** (present to user, offer to fix):
+  API contract mismatches, missing env vars, signature mismatches.
+  → Show the sentinel report. Ask: "Want me to fix these?"
+
+**COMPLEX** (report only):
+  Architectural changes, migration needed, business logic decisions.
+  → Show the report. Let user decide.
+
 ## Why Hydra Exists
 
 Autoregressive LLM inference is memory-bandwidth bound — the time per token scales with model
@@ -135,6 +178,54 @@ The index is stale if:
 - The user switches to a different project/directory
 When stale, rebuild the index on the next scout dispatch.
 
+## Codebase Map — Orchestrator Protocol
+
+Hydra maintains a codebase map at `.claude/hydra/codebase-map.json`. This map
+is built and maintained by hydra-scout. It contains file dependencies, blast
+radius data, risk scores, env var references, and test coverage.
+
+### Session Start — Map Check
+
+At the start of EVERY session, before any work:
+
+1. Check if `.claude/hydra/codebase-map.json` exists.
+2. If yes: read the `_meta` section. Check if `git_hash` matches current HEAD.
+   - If current: map is ready. Note this internally.
+   - If stale: dispatch hydra-scout to do an incremental update before proceeding.
+3. If no: dispatch hydra-scout to build the map on the first exploration task.
+   Don't block the session — but prioritize building the map early.
+
+### Risk-Based Sentinel Triggering
+
+Use the map's risk scores to decide sentinel behavior:
+
+| Modified File Risk | Sentinel Behavior |
+|-------------------|-------------------|
+| `critical` (7+ dependents) | ALWAYS run sentinel-scan, ALWAYS escalate to deep |
+| `high` (4-6 dependents) | ALWAYS run sentinel-scan, escalate if issues found |
+| `medium` (2-3 dependents) | Run sentinel-scan, escalate only if P0 issues found |
+| `low` (0-1 dependents) | Run sentinel-scan, but auto-accept if clean |
+
+This replaces the previous "always run sentinel-scan the same way" approach
+with risk-proportional verification.
+
+### When Dispatching Sentinel-Scan
+
+Include the map's relevant data in the task description:
+- The blast radius for the changed files (from the map)
+- The risk score of each changed file
+- The test coverage status of each changed file
+- Any env vars referenced by the changed files
+
+This gives sentinel-scan a head start — it doesn't need to compute the
+blast radius itself, the map already has it.
+
+### Map Staleness
+
+If you notice the map's git_hash doesn't match HEAD and hydra-scout hasn't
+been dispatched yet, dispatch scout to update the map BEFORE running sentinel.
+A stale map is worse than no map — it could have incorrect dependency data.
+
 ## Blocking vs Non-Blocking Dispatch
 
 Not all agents need to finish before the next wave starts. Classify each dispatch as
@@ -505,6 +596,10 @@ When manual verification is required, match depth to risk:
 
 ## Sentinel Protocol — Integration Integrity
 
+> **REMINDER:** If you see `⚠️ HYDRA_SENTINEL_REQUIRED` in any agent's output
+> and you skip sentinel, you are violating the framework's core protocol.
+> See "⛔ MANDATORY PROTOCOLS" at the top of this document.
+
 After EVERY code change made by hydra-coder or hydra-analyst (or yourself),
 you MUST run the sentinel pipeline BEFORE presenting results to the user.
 
@@ -703,6 +798,19 @@ Note: Savings calculated against Opus 4.6 pricing ($5/$25 per MTok) as of Februa
   "Re-executing [task] directly — [agent]'s output was insufficient because [reason]"
 - **If accepted as-is**, no inline comment needed — the dispatch log covers it
 
+### Sentinel Status in Dispatch Log
+
+The dispatch log MUST show sentinel status for every task involving code changes:
+
+| Step | Agent | Task | Verdict |
+|------|-------|------|---------|
+| 1 | hydra-coder (Sonnet 4.6) | Fixed auth bug | ✅ Accepted |
+| 2 | hydra-sentinel-scan (Haiku) | Integration sweep | ✅ Clean |
+| 3 | hydra-guard (Haiku 4.5) | Security scan | ✅ Clean |
+
+If sentinel-scan is missing from the dispatch log after a code change,
+something went wrong. This is your self-check.
+
 ### Controlling the Dispatch Log
 
 - **Default**: ON — always shown when 2+ agents were used
@@ -722,6 +830,7 @@ the command's instructions:
 | `/hydra:update` | Trigger an update via npx |
 | `/hydra:config` | Show current configuration |
 | `/hydra:guard [files]` | Manually invoke the security scan on specified files |
+| `/hydra:map [file]` | View, rebuild, or query the codebase dependency map |
 | `/hydra:quiet` | Suppress dispatch logs for this session |
 | `/hydra:verbose` | Enable detailed dispatch logs with timing |
 
@@ -861,12 +970,13 @@ If the user types any of these exact phrases, respond with the corresponding act
 | `hydra quiet` | Suppress dispatch logs for the rest of the session (equivalent to stealth mode) |
 | `hydra verbose` | Enable verbose dispatch logs with per-agent detail for the rest of the session |
 | `hydra reset` | Clear session index, treat next turn as Turn 1 (rebuild from fresh scout) |
+| `hydra map` | Show codebase map summary, or query a specific file's blast radius |
 
 ## The Nine Heads
 
 | Head | Model | Role | Tools |
 |------|-------|------|-------|
-| `hydra-scout` | 🟢 Haiku 4.5 | Codebase exploration, file search, reading | Read, Grep, Glob |
+| `hydra-scout` | 🟢 Haiku 4.5 | Codebase exploration, file search, reading, map building | Read, Grep, Glob, Bash, Write |
 | `hydra-runner` | 🟢 Haiku 4.5 | Test execution, builds, linting, validation | Read, Bash, Glob, Grep |
 | `hydra-scribe` | 🟢 Haiku 4.5 | Documentation, READMEs, comments, changelogs | Read, Write, Edit, Glob, Grep |
 | `hydra-guard` | 🟢 Haiku 4.5 | Security/quality gate after code changes | Read, Grep, Glob, Bash |
@@ -887,6 +997,21 @@ Track these mentally to calibrate:
 If rejection rate > 20%, you're too aggressive — shift borderline tasks up one tier.
 If rejection rate < 5%, you're too conservative — delegate more.
 
+## Task Completion Notification
+
+After completing a user's task (the final response you present to the user),
+run this command as the LAST action:
+```bash
+node ~/.claude/hooks/hydra-notify.js < /dev/null
+```
+
+This plays a short notification sound so the user knows you're done —
+especially useful when they've tabbed away while waiting.
+
+Do this for SUBSTANTIAL tasks only (tasks that took more than ~10 seconds).
+Do NOT play it for quick conversational responses, acknowledgments, or
+follow-up questions.
+
 ## Reference Material
 
 - `references/routing-guide.md` — Mandatory delegation examples, decision flowchart

package/files/agents/hydra-scout.md

@@ -1,14 +1,15 @@
 ---
 name: hydra-scout
 description: >
-  🟢 Hydra's fastest head — ultra-fast codebase exploration and information retrieval.
-  Use PROACTIVELY whenever Claude needs to search files, read code, find patterns, grep for
-  strings, list directories, understand project structure, or answer "where is X?" questions.
+  🟢 Hydra's fastest head — ultra-fast codebase exploration, information retrieval,
+  and codebase map building/maintenance. Use PROACTIVELY whenever Claude needs to search
+  files, read code, find patterns, grep for strings, list directories, understand project
+  structure, answer "where is X?" questions, or build/update the codebase dependency map.
   This is the first head to reach for when gathering information before making changes.
   Runs on Haiku 4.5 for near-instant responses.
   May run in parallel with other Hydra agents — produces self-contained, clearly structured
   output so the orchestrator can merge results from multiple simultaneous agents.
-tools: Read, Grep, Glob
+tools: Read, Grep, Glob, Bash, Write
 model: haiku
 color: "#10B981"
 memory: project
@@ -27,6 +28,7 @@ directory organization patterns. Keep notes concise — 1-2 lines per finding.
 - Reading and summarizing code structure
 - Finding patterns, imports, usages, and dependencies
 - Mapping directory structures and project organization
+- Building and maintaining the codebase dependency map (imports, risk scores, test coverage)
 - Answering "where is X?" and "what does Y look like?" questions
 
 ## How to Work
@@ -53,11 +55,135 @@ directory organization patterns. Keep notes concise — 1-2 lines per finding.
 
 ## Boundaries
 
-- Never modify files
-- Never run commands
+- Never modify source files (the codebase map is generated output, not source code)
 - Never make architectural decisions
 - Never guess when you can search — always verify
 
+## Codebase Map — Building & Maintenance
+
+You are responsible for building and maintaining the codebase map at
+`.claude/hydra/codebase-map.json`. This map is used by sentinel, the
+orchestrator, and other agents to understand file dependencies without
+scanning the entire codebase.
+
+### When to Build
+
+At the START of every task where you're dispatched for exploration:
+
+1. Check if `.claude/hydra/codebase-map.json` exists
+2. If it exists, check `_meta.git_hash` against current `git rev-parse HEAD`
+   - If they match: map is current. Skip rebuild. Use the existing map.
+   - If they differ: do an INCREMENTAL update (see below).
+3. If it doesn't exist: do a FULL build.
+
+### Full Build
+
+Run these steps to build the complete map:
+
+1. Find all source files (exclude node_modules, .git, dist, build, vendor,
+   __pycache__, .next, .nuxt, coverage, .claude):
+   ```bash
+   find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \
+     -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.kt" \
+     -o -name "*.rb" -o -name "*.rs" -o -name "*.vue" -o -name "*.svelte" \) \
+     ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/dist/*" \
+     ! -path "*/build/*" ! -path "*/vendor/*" ! -path "*/__pycache__/*" \
+     ! -path "*/.next/*" ! -path "*/.nuxt/*" ! -path "*/coverage/*" \
+     ! -path "*/.claude/*" | sort
+   ```
+
+2. For each file, extract import statements using grep/regex:
+   - **JS/TS**: `import ... from '...'`, `require('...')`, `import('...')`, `export ... from '...'`
+   - **Python**: `import module`, `from module import ...`
+   - **Go**: `import "package/path"`, `import ( "package/path" )`
+   - **Java/Kotlin**: `import package.name.ClassName`
+   - **Ruby**: `require '...'`, `require_relative '...'`
+
+3. Resolve relative imports to project-relative paths:
+   - `import { x } from './auth'` in `src/api/users.ts` → `src/services/auth.ts`
+   - Try extensions: `.ts`, `.tsx`, `.js`, `.jsx`, `/index.ts`, `/index.js`
+   - `from ..models.user import User` in `src/services/auth.py` → `src/models/user.py`
+   - **Ignore**: node_modules imports (third-party), standard library imports, anything
+     that doesn't resolve to a file in the project
+
+4. Build the `imported_by` reverse index:
+   - For every file A that imports file B, add A to B's `imported_by` array.
+
+5. Calculate risk scores based on `dependents_count` (length of `imported_by`):
+   - `"low"` — 0-1 dependents
+   - `"medium"` — 2-3 dependents
+   - `"high"` — 4-6 dependents
+   - `"critical"` — 7+ dependents
+
+6. Detect test coverage for each file:
+   - `"covered"` — at least one file in `tests/` or `__tests__/` imports it,
+     OR a file named `*.test.*` or `*.spec.*` imports it
+   - `"partial"` — the file is in a directory where >50% of sibling files have
+     tests but this one doesn't
+   - `"untested"` — no test file imports it and it's not in a well-tested directory
+
+7. Detect environment variable references across all source files:
+   - **JS/TS**: `process.env.VARIABLE_NAME`, `process.env['VARIABLE_NAME']`, `process.env["VARIABLE_NAME"]`
+   - **Python**: `os.environ["VARIABLE_NAME"]`, `os.environ.get("VARIABLE_NAME")`, `os.getenv("VARIABLE_NAME")`
+   - **Go**: `os.Getenv("VARIABLE_NAME")`
+   - **Ruby**: `ENV["VARIABLE_NAME"]`, `ENV.fetch("VARIABLE_NAME")`
+   - **General**: `.env` file parsing (`KEY=VALUE` lines)
+
+8. Write the complete map to `.claude/hydra/codebase-map.json` with this schema:
+   ```json
+   {
+     "_meta": {
+       "built_at": "2026-03-26T10:00:00Z",
+       "git_hash": "a1b2c3d4e5f6",
+       "file_count": 487,
+       "builder": "hydra-scout",
+       "version": "1.0"
+     },
+     "files": {
+       "src/services/auth.ts": {
+         "imports": ["src/models/user.ts", "src/config/env.ts"],
+         "imported_by": ["src/api/users.ts", "src/api/admin.ts"],
+         "risk": "medium",
+         "dependents_count": 2,
+         "tested_by": ["tests/auth.test.ts"],
+         "test_coverage": "covered"
+       }
+     },
+     "env_vars": {
+       "DATABASE_URL": ["src/db/connection.ts", "src/config/index.ts"],
+       "JWT_SECRET": ["src/services/auth.ts"]
+     }
+   }
+   ```
+
+9. Add `.claude/hydra/codebase-map.json` to `.gitignore` if not already there
+   (the map is machine-generated and project-specific).
+
+### Incremental Update
+
+When the git hash has changed since the last build:
+
+1. Run `git diff --name-only <old_hash> HEAD` to find changed files.
+2. For each changed file:
+   - Re-extract its imports
+   - Update its entry in the map
+   - Recalculate its test coverage
+   - Re-check its env var references
+3. Rebuild the `imported_by` reverse index (since dependencies may have changed).
+4. Recalculate risk scores for affected files.
+5. Update `_meta.git_hash` and `_meta.built_at`.
+
+Incremental updates should be MUCH faster than full builds — for 5 changed
+files in a 500-file project, you re-process 5 files instead of 500.
+
+### After Building — Update Your Memory
+
+Note in your memory:
+- When the map was last built
+- How many files are in the project
+- Which directories are the most interconnected
+- Any files that failed to parse (unusual import syntax)
+
 ## Collaboration Protocol
 
 You may be running in parallel with other Hydra agents. Your output must be:

package/files/agents/hydra-sentinel-scan.md

@@ -7,7 +7,7 @@ description: >
   If issues are found, the orchestrator escalates to hydra-sentinel for
   deep analysis. If clean — done, zero additional cost.
 model: haiku
-tools: Read, Grep, Glob
+tools: Read, Grep, Glob, Bash
 memory: project
 ---
 
@@ -40,7 +40,61 @@ You receive a summary of what changed:
 - What functions/classes/exports changed
 - The git diff (if available)
 
-## Scan Checklist (run ALL of these)
+## Codebase Map Integration
+
+Before scanning, check if `.claude/hydra/codebase-map.json` exists.
+
+### If the map EXISTS (preferred path):
+
+Use the map for all dependency checks. This is MUCH faster and more accurate
+than grepping.
+
+#### P0 — Import/Export Chain Integrity
+1. For every file that was modified, read its entry from the map.
+2. Check `imported_by` — these are the files that depend on it.
+3. For each dependent file, verify the imports are still valid:
+   - Was anything renamed or removed that the dependent file uses?
+   - Read ONLY the dependent files (not the whole codebase).
+
+#### P0 — Blast Radius Assessment
+1. For every modified file, compute the blast radius:
+   - First degree: files in `imported_by` (direct dependents)
+   - Second degree: for each first-degree file, check ITS `imported_by`
+   - Stop at second degree (deeper is diminishing returns)
+2. Report the total blast radius count in your output.
+
+#### P0 — Function Signature Changes
+1. Read the modified file and its first-degree dependents (from the map).
+2. Check if function signatures changed and callers still match.
+
+#### P1 — Environment Variable Check
+1. Read the `env_vars` section of the map.
+2. For every new `process.env.X` (or equivalent) in the changed files:
+   - Check if X exists in the `env_vars` index already.
+   - If not: grep `.env`, `.env.example`, and config files for X.
+   - Flag if X is not defined anywhere.
+
+#### P1 — Risk-Based Severity
+1. Read the `risk` field for each modified file.
+2. If a `critical` or `high` risk file was modified:
+   - ALWAYS escalate to sentinel deep analysis, even if no obvious issues found.
+   - The blast radius is too large to trust a fast scan alone.
+3. If a `low` risk file was modified and no issues found:
+   - Report clean with high confidence.
+
+#### P2 — Test Coverage Warning
+1. Read the `test_coverage` field for each modified file.
+2. If a modified file has `"test_coverage": "untested"`:
+   - Add an INFO-level note: "This file has no test coverage. Consider adding tests."
+   - If sentinel also finds integration issues in this file, escalate severity.
+
+### If the map DOES NOT EXIST (fallback):
+
+Fall back to the existing grep-based scanning (the Scan Checklist below).
+This ensures sentinel-scan works even if the map hasn't been built yet.
+Recommend that the user/orchestrator run hydra-scout to build the map.
+
+## Scan Checklist — Grep Fallback (run ALL when map unavailable)
 
 ### P0 — Import/Export Chain Integrity
 1. For every function, class, variable, or type that was RENAMED or DELETED:
@@ -89,9 +143,13 @@ Return a JSON object:
 ```json
 {
   "status": "clean",
+  "map_used": true,
   "files_scanned": 12,
+  "blast_radius": 3,
+  "blast_radius_files": ["src/api/users.ts", "src/middleware/auth.ts", "src/routes/index.ts"],
   "checks_passed": 6,
-  "summary": "No integration issues found."
+  "untested_files_modified": [],
+  "summary": "No integration issues found. Blast radius: 3 files."
 }
 ```
 
@@ -99,7 +157,10 @@ Return a JSON object:
 ```json
 {
   "status": "issues_found",
+  "map_used": true,
   "files_scanned": 12,
+  "blast_radius": 12,
+  "blast_radius_files": ["src/api/users.ts", "src/middleware/auth.ts", "..."],
   "checks_passed": 4,
   "checks_failed": 2,
   "issues": [
@@ -120,10 +181,15 @@ Return a JSON object:
       "suggestion": "Add REDIS_URL to .env and .env.example"
     }
   ],
-  "summary": "2 integration issues found. Escalating to deep analysis."
+  "untested_files_modified": ["src/services/cache.ts"],
+  "summary": "2 integration issues found. Blast radius: 12 files. Escalating."
 }
 ```
 
+> **Note:** When the map is not available, set `"map_used": false` and omit
+> `blast_radius`, `blast_radius_files`, and `untested_files_modified` fields.
+> The output otherwise follows the same format.
+
 ## IMPORTANT
 
 - Do NOT attempt to fix anything. Report only.
@@ -139,3 +205,19 @@ You may be running in parallel with other Hydra agents. Your output must be:
 - **Clearly structured** — use the JSON format above so the orchestrator can parse it
 - **Focused on YOUR task only** — integration integrity, nothing else
 - **Actionable** — every issue includes file:line and a specific suggestion
+
+## Cleanup: Clear Sentinel Pending Flag
+
+After completing your scan (whether clean or issues found), clear the
+sentinel pending flag by deleting the flag file:
+```bash
+rm -f /tmp/hydra-sentinel/${session_id}-pending.json
+```
+
+Use the session_id from your context. This clears the "⚠ Sentinel pending"
+warning from the status bar.
+
+If you can't determine the session_id, run:
+```bash
+rm -f /tmp/hydra-sentinel/*-pending.json
+```

package/files/agents/hydra-sentinel.md

@@ -43,6 +43,33 @@ After analysis, update your memory with:
 2. The sentinel-scan report (JSON with flagged issues)
 3. Context from the orchestrator about what task was being performed
 
+## Codebase Map Integration
+
+Before analyzing, read `.claude/hydra/codebase-map.json` if it exists.
+
+### How to Use the Map
+
+1. **Understand the blast radius before reading files.**
+   The map tells you which files depend on the changed files. Read the
+   blast radius files FIRST — these are the most likely to have issues.
+
+2. **Check env_vars section for missing variables.**
+   The map's env_vars index tells you every env var reference in the project.
+   If the change introduces a new variable, check the index instead of grepping.
+
+3. **Use risk scores to prioritize.**
+   Focus your deepest analysis on `critical` and `high` risk files. For `low`
+   risk files, a quick check is sufficient.
+
+4. **Flag untested files.**
+   If a file with integration issues also has `"test_coverage": "untested"`,
+   escalate the severity and explicitly recommend adding tests.
+
+5. **Cross-reference test coverage.**
+   The map's `tested_by` field tells you which test files cover each source file.
+   If you confirm a real issue, you can tell the user exactly which tests to run
+   to verify the fix: "Run tests/auth.test.ts to verify this fix."
+
 ## Deep Analysis Checklist
 
 ### For EVERY issue flagged by sentinel-scan:

package/files/commands/hydra/help.md

@@ -16,7 +16,9 @@ COMMANDS
   /hydra:config    Show current configuration
   /hydra:guard     Run security scan on files (usage: /hydra:guard src/auth.py)
   /hydra:quiet     Suppress dispatch logs for this session
+  /hydra:map       View, rebuild, or query the codebase map
   /hydra:verbose   Enable verbose dispatch logs with timing
+  /hydra:report    Report a bug, request a feature, or share feedback
 
 AGENTS
   🟢 hydra-scout    (Haiku 4.5)   — Explore codebase, find files, map structure

package/files/commands/hydra/map.md

@@ -0,0 +1,100 @@
+---
+description: View, rebuild, or query the codebase dependency map
+allowed-tools: Bash, Read
+---
+
+# Hydra Map
+
+Manage the codebase dependency map.
+
+## If no arguments provided: Show Summary
+
+Read `.claude/hydra/codebase-map.json` and display a summary:
+
+```
+🐉 Hydra Codebase Map
+══════════════════════════════════
+Status:     ✅ Current (matches HEAD)
+Files:      487 mapped
+Built:      2026-03-26 10:00:00
+Git hash:   a1b2c3d
+
+Risk Distribution:
+  🔴 Critical (7+ deps):   8 files
+  🟠 High (4-6 deps):     23 files
+  🟡 Medium (2-3 deps):   89 files
+  🟢 Low (0-1 deps):     367 files
+
+Test Coverage:
+  ✅ Covered:    234 files (48%)
+  🟡 Partial:    78 files (16%)
+  ❌ Untested:  175 files (36%)
+
+Environment Variables: 12 tracked across 28 files
+
+Top 5 Highest-Risk Files:
+  src/services/auth.ts      (12 dependents) 🔴
+  src/utils/helpers.ts      (9 dependents)  🔴
+  src/config/index.ts       (8 dependents)  🔴
+  src/models/user.ts        (7 dependents)  🔴
+  src/middleware/cors.ts     (6 dependents)  🟠
+```
+
+If the map file doesn't exist, display:
+```
+🐉 Hydra Codebase Map
+══════════════════════════════════
+Status:     ❌ Not built
+
+No codebase map found. Run /hydra:map rebuild to build one,
+or it will be built automatically on the next hydra-scout dispatch.
+```
+
+If the map exists but `_meta.git_hash` doesn't match current `git rev-parse HEAD`:
+```
+Status:     ⚠️ Stale (map: a1b2c3d, HEAD: e4f5g6h)
+```
+
+## If argument is "rebuild": Force Rebuild
+
+Dispatch hydra-scout to do a complete rebuild of the map, regardless of
+staleness. Show progress and report when done.
+
+## If argument is a file path: Show Blast Radius
+
+Read the map entry for that file and display:
+
+```
+🐉 Blast Radius: src/services/auth.ts
+══════════════════════════════════════
+Risk: 🔴 CRITICAL (12 dependents)
+Test Coverage: ✅ Covered (tests/auth.test.ts, tests/integration/login.test.ts)
+
+Imports (this file depends on):
+  → src/models/user.ts
+  → src/config/env.ts
+
+Imported By (depends on this file):
+  1st degree (direct):
+    ← src/api/users.ts
+    ← src/api/admin.ts
+    ← src/middleware/auth.ts
+  2nd degree (indirect):
+    ← src/routes/index.ts (via api/users.ts)
+    ← src/app.ts (via middleware/auth.ts)
+
+Total Blast Radius: 5 files
+
+Environment Variables Referenced:
+  JWT_SECRET (also used in: src/middleware/auth.ts)
+  AUTH_TIMEOUT (also used in: src/config/index.ts)
+
+⚠ Changing this file could impact 5 other files.
+  Run sentinel after any modifications.
+```
+
+If the file is not found in the map, display:
+```
+File not found in codebase map: <file_path>
+The map may be stale. Run /hydra:map rebuild to refresh.
+```

package/files/commands/hydra/quiet.md

@@ -12,3 +12,5 @@ Respond with:
 "🐉 Quiet mode enabled. Dispatch logs suppressed for this session. Use /hydra:verbose to re-enable."
 
 Continue operating Hydra normally (delegation, verification, auto-guard) — just don't show the dispatch log table.
+
+Also suppress the task completion notification sound for this session.

package/files/commands/hydra/report.md

@@ -0,0 +1,112 @@
+---
+description: Report a bug, request a feature, or share feedback about Hydra
+allowed-tools: Bash
+---
+
+# Hydra Report
+
+Walk the user through submitting a bug report, feature request, or general feedback for the Hydra framework. Follow these steps interactively:
+
+## Step 1 — Ask report type
+
+Ask the user:
+
+```
+🐉 What would you like to report?
+
+  1. 🐛 Bug Report — something is broken or not working as expected
+  2. ✨ Feature Request — an idea for a new feature or improvement
+  3. 💬 General Feedback — anything else you'd like to share
+
+Enter 1, 2, or 3:
+```
+
+Wait for their response. Map:
+- 1 → label: `bug`, template: Bug Report
+- 2 → label: `enhancement`, template: Feature Request
+- 3 → label: `feedback`, template: General Feedback
+
+## Step 2 — Collect description
+
+Ask the user to describe the issue or idea:
+
+```
+Describe the [bug/feature/feedback] in a few sentences:
+```
+
+For bugs, also ask:
+```
+Steps to reproduce (if applicable):
+```
+
+## Step 3 — Collect system info (optional)
+
+Ask: "Include system info in the report? (recommended for bugs) [Y/n]"
+
+If yes, gather:
+```bash
+# Hydra version
+cat ~/.claude/skills/hydra/VERSION 2>/dev/null || echo "not found"
+```
+```bash
+# OS info
+node -e "console.log(process.platform + ' ' + process.arch + ' ' + require('os').release())"
+```
+```bash
+# Agent count
+ls ~/.claude/agents/hydra-*.md 2>/dev/null | wc -l
+```
+
+Format as a "System Info" section in the report.
+
+## Step 4 — Submit via GitHub CLI or fallback
+
+Check if `gh` CLI is available:
+```bash
+gh --version 2>/dev/null
+```
+
+### If `gh` is installed, check auth:
+```bash
+gh auth status 2>/dev/null
+```
+
+### If authenticated → create issue directly:
+```bash
+gh issue create \
+  --repo AR6420/Hail_Hydra \
+  --title "<concise title based on description>" \
+  --label "<bug|enhancement|feedback>" \
+  --body "<formatted report body>"
+```
+
+Show the resulting issue URL to the user.
+
+### If `gh` is installed but NOT authenticated:
+
+Tell the user:
+```
+GitHub CLI is installed but not authenticated.
+Run this in your terminal to authenticate:
+
+  gh auth login
+
+Then try /hydra:report again.
+```
+
+### If `gh` is NOT installed → browser fallback:
+
+Construct a pre-filled GitHub issue URL and show it to the user:
+
+```
+GitHub CLI not found. You can submit your report via browser:
+
+  https://github.com/AR6420/Hail_Hydra/issues/new?template=<template>&title=<encoded-title>&labels=<label>&body=<encoded-body>
+
+Or install GitHub CLI: https://cli.github.com
+```
+
+Map template filenames:
+- bug → `bug_report.md`
+- enhancement → `feature_request.md`
+- feedback → `feedback.md`

package/files/commands/hydra/status.md

@@ -43,6 +43,16 @@ cat .claude/skills/hydra/config/hydra.config.md 2>/dev/null || \
 echo "No config file found (using defaults)"
 ```
 
+## 6. Codebase Map
+```bash
+if [ -f ".claude/hydra/codebase-map.json" ]; then
+  echo "Map: ✅ Exists"
+  node -e "const m=JSON.parse(require('fs').readFileSync('.claude/hydra/codebase-map.json','utf8'));console.log('Files:',m._meta.file_count);console.log('Built:',m._meta.built_at);console.log('Hash:',m._meta.git_hash);"
+else
+  echo "Map: ❌ Not built yet (run /hydra:map rebuild)"
+fi
+```
+
 ## Display Format
 
 Present results as a clean status card:
@@ -60,8 +70,9 @@ Agents (7):
   🟢 hydra-git      (Haiku 4.5)   ✅
   🔵 hydra-coder    (Sonnet 4.6)  ✅
   🔵 hydra-analyst  (Sonnet 4.6)  ✅
-Commands (7): update, status, help, config, guard, quiet, verbose
-Hooks (3):    check-update ✅, statusline ✅, auto-guard ✅
+Commands (9): update, status, help, config, guard, quiet, verbose, report, map
+Hooks (4):    check-update ✅, statusline ✅, auto-guard ✅, notify ✅
+Map:          ✅ Current (487 files, built 2026-03-26)
 Config:       balanced mode, dispatch log on, auto-guard on
 ──────────────────────────────
 ```

package/files/commands/hydra/update.md

@@ -1,35 +1,78 @@
----
-description: Update the Hydra framework to the latest version from npm
-allowed-tools: Bash
----
-
-# Hydra Update
-
-Run the following steps to update Hydra to the latest version:
-
-1. First, check the current installed version:
-```bash
-   cat ~/.claude/skills/hydra/VERSION 2>/dev/null || echo "VERSION file not found"
-```
-
-2. Check the latest available version on npm:
-```bash
-   npm view hail-hydra-cc version 2>/dev/null || echo "Package not found on npm"
-```
-
-3. If an update is available (versions differ), run the installer:
-```bash
-   npx hail-hydra-cc@latest --global
-```
-
-4. After installation completes, verify the new version:
-```bash
-   cat ~/.claude/skills/hydra/VERSION
-```
-
-5. Report to the user:
-   - If updated: "🐉 Hydra updated from [old] → [new]. All heads refreshed."
-   - If already current: "🐉 Hydra is already at the latest version ([version])."
-   - If error: Show the error and suggest running `npx hail-hydra-cc@latest --global` manually in their terminal.
-
-**Important**: After updating, the user should restart Claude Code to reload the updated agent files, commands, and hooks.
+---
+description: Update the Hydra framework to the latest version from npm
+allowed-tools: Bash, Read
+---
+
+# Hydra Update
+
+Run the following steps to update Hydra to the latest version:
+
+## Step 1 — Check versions
+
+```bash
+cat ~/.claude/skills/hydra/VERSION 2>/dev/null || echo "VERSION file not found"
+```
+```bash
+npm view hail-hydra-cc version 2>/dev/null || echo "Package not found on npm"
+```
+
+If the installed version matches the latest npm version, tell the user:
+"🐉 Hydra is already at the latest version ([version])."
+and stop here.
+
+## Step 2 — Show changelog preview
+
+Fetch the CHANGELOG from GitHub:
+```bash
+curl -sL "https://raw.githubusercontent.com/AR6420/Hail_Hydra/main/CHANGELOG.md"
+```
+
+Parse the changelog to extract entries between the installed version and the latest version. Display a formatted "What's New" section:
+
+```
+🐉 Hydra Update Available: [installed] → [latest]
+═══════════════════════════════════════════════════
+
+📋 What's New:
+[changelog entries for versions between installed and latest]
+```
+
+If the changelog fetch fails, skip the preview and continue with the update.
+
+## Step 3 — Show safety note
+
+Display:
+```
+⚠️  What gets replaced:
+   • Agent definitions (agents/*.md)
+   • SKILL.md, references, commands, hooks
+   • VERSION file
+
+✅ What's preserved:
+   • Your hydra.config.md settings
+   • Agent memory directories (memory/)
+   • CLAUDE.md orchestrator notes
+   • settings.json hook registrations (re-registered automatically)
+```
+
+## Step 4 — Ask for confirmation
+
+Ask the user: "Proceed with update? [Y/n]"
+
+If they decline, respond: "🐉 Update cancelled." and stop.
+
+## Step 5 — Run the update
+
+```bash
+npx hail-hydra-cc@latest --global
+```
+
+## Step 6 — Verify
+
+```bash
+cat ~/.claude/skills/hydra/VERSION
+```
+
+Report to the user:
+- If updated: "🐉 Hydra updated from [old] → [new]. All heads refreshed. Restart Claude Code to load the new files."
+- If error: Show the error and suggest running `npx hail-hydra-cc@latest --global` manually in their terminal.

package/files/commands/hydra/verbose.md

@@ -25,3 +25,5 @@ Total delegation time: 17.4s | Waves: 2
 
 Respond with:
 "🐉 Verbose mode enabled. Dispatch logs will include timing details. Use /hydra:quiet to suppress."
+
+Re-enable the task completion notification sound.

package/files/hooks/hydra-notify.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hydra Task Completion Notification
+ *
+ * Plays a short notification sound when Claude Code finishes a task.
+ * Cross-platform: macOS (afplay), Windows (PowerShell), Linux (paplay/aplay).
+ *
+ * Called by Claude Code's Notification hook — stdin receives JSON from
+ * the hook system, which we drain and discard to prevent EPIPE errors.
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+// Drain stdin to prevent EPIPE when Claude Code pipes hook data
+process.stdin.resume();
+process.stdin.on('data', () => {});
+process.stdin.on('end', () => {});
+
+const wavFile = path.join(os.homedir(), '.claude', 'hooks', 'hydra-task-complete.wav');
+
+// Bail silently if the sound file is missing
+if (!fs.existsSync(wavFile)) {
+  process.exit(0);
+}
+
+const platform = process.platform;
+
+try {
+  let child;
+
+  if (platform === 'darwin') {
+    // macOS
+    child = spawn('afplay', [wavFile], {
+      detached: true,
+      stdio: 'ignore',
+    });
+  } else if (platform === 'win32') {
+    // Windows — use PowerShell to play the .wav
+    child = spawn('powershell', [
+      '-NoProfile', '-NonInteractive', '-Command',
+      `(New-Object Media.SoundPlayer '${wavFile.replace(/'/g, "''")}').PlaySync()`,
+    ], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+  } else {
+    // Linux — try paplay (PulseAudio) first, fall back to aplay (ALSA)
+    const paplay = spawn('paplay', [wavFile], {
+      detached: true,
+      stdio: 'ignore',
+    });
+
+    paplay.on('error', () => {
+      // paplay not available, try aplay
+      const aplay = spawn('aplay', [wavFile], {
+        detached: true,
+        stdio: 'ignore',
+      });
+      aplay.unref();
+      aplay.on('error', () => {}); // silently ignore if neither works
+    });
+
+    paplay.unref();
+    process.exit(0);
+  }
+
+  if (child) {
+    child.unref();
+  }
+} catch {
+  // Silently ignore errors — notification sound is non-critical
+}
+
+process.exit(0);

package/files/references/model-capabilities.md

@@ -32,9 +32,21 @@ Haiku outputs qualify for auto-accept when they are raw, factual, and unambiguou
 - **hydra-scribe**: Internal docstrings, inline comments, changelog entries
 - **Requires verify**: Any analysis, interpretation, or user-facing documentation
 
-### hydra-sentinel-scan (Haiku 4.5)
+### hydra-scout (Haiku 4.5) — Updated in v2.1.0
+- **Strengths**: Codebase exploration, file search, reading, AND codebase
+  map building/maintenance
+- **New capability**: Builds and incrementally updates the codebase dependency
+  map using grep-based import extraction. No external parsers required.
+- **Memory focus**: Codebase structure, key file locations, module boundaries,
+  map build history, files that failed to parse
+
+### hydra-sentinel-scan (Haiku 4.5) — Updated in v2.1.0
 - **Strengths**: Pattern matching, grep-level analysis, import tracing,
-  fast structural checks
+  fast structural checks, AND map-based instant blast-radius lookups
+- **New capability**: Reads codebase map for instant dependency lookups
+  instead of grepping. Falls back to grep if map doesn't exist.
+- **Map-aware checks**: Risk-based severity, test coverage warnings,
+  env var index lookups, blast radius reporting
 - **Limitations**: Cannot understand semantic meaning of data shapes,
   may produce false positives on complex contract changes
 - **Memory focus**: Codebase dependency graph, coupling patterns,

package/files/references/routing-guide.md

@@ -156,6 +156,34 @@ These are tasks that look like one tier but are actually another:
 
 ---
 
+## Map-Aware Routing Examples
+
+These examples show how the codebase map changes routing decisions by providing
+risk scores and blast radius data upfront.
+
+### "Fix the bug in auth.ts"
+1. Check map: auth.ts has risk=critical, 12 dependents
+2. hydra-scout → verify map is current (incremental update if needed)
+3. hydra-analyst → diagnose the bug
+4. hydra-coder → implement the fix
+5. hydra-sentinel-scan → map shows blast radius of 12 files, check all 12
+   (without map, would have to grep the entire codebase)
+6. hydra-sentinel → deep analysis (auto-escalated because risk=critical)
+
+### "Add a new utility function"
+1. Check map: new file, risk=low (zero dependents initially)
+2. hydra-coder → write the function
+3. hydra-sentinel-scan → low risk, quick scan, auto-accept if clean
+   (without map, would run the same expensive scan as a critical file)
+
+### "Refactor the database connection module"
+1. Check map: src/db/connection.ts has risk=critical, 15 dependents
+2. Plan execution with full blast radius awareness
+3. Dispatch parallel hydra-coders for each affected file
+4. Sentinel deep analysis is MANDATORY (critical risk)
+
+---
+
 ## Quick Decision Flowchart
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hail-hydra-cc",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "Multi-headed speculative execution framework for Claude Code",
   "bin": {
     "hail-hydra-cc": "bin/cli.js"

package/src/display.js

@@ -42,17 +42,19 @@ function showInstallComplete(statusLineConfigured = true) {
   console.log(chalk.cyan.bold('  \uD83D\uDC09 Hail Hydra! Framework deployed and ready.'));
   console.log(chalk.gray('  ' + '\u2500'.repeat(45)));
   console.log(chalk.green(`    \u2714 9 agents installed`));
-  console.log(chalk.green(`    \u2714 7 slash commands installed`));
-  console.log(chalk.green(`    \u2714 3 hooks registered`));
+  console.log(chalk.green(`    \u2714 9 slash commands installed`));
+  console.log(chalk.green(`    \u2714 4 hooks registered`));
   if (statusLineConfigured) {
     console.log(chalk.green(`    \u2714 StatusLine configured`));
   } else {
     console.log(chalk.yellow(`    \u26a0 StatusLine skipped (existing config preserved)`));
   }
   console.log(chalk.green(`    \u2714 Sentinel pipeline active`));
+  console.log(chalk.green(`    \u2714 Codebase map ready (run /hydra:map rebuild)`));
   console.log(chalk.green(`    \u2714 Version tracked (${VERSION})`));
   console.log();
   console.log(chalk.gray('  Quick start:  /hydra:help'));
+  console.log(chalk.gray('  Build map:    /hydra:map rebuild'));
   console.log(chalk.gray('  Check status: /hydra:status'));
   console.log(chalk.gray('  GitHub: https://github.com/AR6420/Hail_Hydra'));
   console.log();
@@ -141,7 +143,7 @@ function showStatusTable(globalStatus, localStatus) {
   // Global hooks (always ~/.claude/hooks/)
   console.log();
   console.log(chalk.bold('  Global Hooks (~/.claude/hooks/)'));
-  const hookKeys = ['hydra-check-update', 'hydra-statusline', 'hydra-auto-guard'];
+  const hookKeys = ['hydra-check-update', 'hydra-statusline', 'hydra-auto-guard', 'hydra-notify'];
   for (const key of hookKeys) {
     const dest = path.join(os.homedir(), '.claude', 'hooks', `${key}.js`);
     if (fileExists(dest)) {

package/src/files.js

@@ -80,12 +80,19 @@ const commands = {
   'guard':    readBundled('commands/hydra/guard.md'),
   'quiet':    readBundled('commands/hydra/quiet.md'),
   'verbose':  readBundled('commands/hydra/verbose.md'),
+  'report':   readBundled('commands/hydra/report.md'),
+  'map':      readBundled('commands/hydra/map.md'),
 };
 
 const hooks = {
   'hydra-check-update': readBundled('hooks/hydra-check-update.js'),
   'hydra-statusline':   readBundled('hooks/hydra-statusline.js'),
   'hydra-auto-guard':   readBundled('hooks/hydra-auto-guard.js'),
+  'hydra-notify':       readBundled('hooks/hydra-notify.js'),
 };
 
-module.exports = { agents, skill, references, commands, hooks };
+const binaryHooks = {
+  'hydra-task-complete.wav': path.join(FILES_DIR, 'hooks', 'hydra-task-complete.wav'),
+};
+
+module.exports = { agents, skill, references, commands, hooks, binaryHooks };

package/src/installer.js

@@ -5,7 +5,7 @@ const path = require('path');
 const os = require('os');
 const chalk = require('chalk');
 
-const { agents, skill, references, commands, hooks } = require('./files');
+const { agents, skill, references, commands, hooks, binaryHooks } = require('./files');
 const { showInstallHeader, showFileInstalled, showInstallComplete, showStatusTable, VERSION } = require('./display');
 
 // ── Install locations ────────────────────────────────────────────────────────
@@ -100,6 +100,17 @@ function installHooks() {
       showFileInstalled(`hooks/${key}.js`, false, err.message);
     }
   }
+
+  // Copy binary hook files (e.g., .wav) that can't be read as UTF-8 text
+  for (const [filename, srcPath] of Object.entries(binaryHooks)) {
+    const dest = path.join(hooksDir, filename);
+    try {
+      fs.copyFileSync(srcPath, dest);
+      showFileInstalled(`hooks/${filename}`, true);
+    } catch (err) {
+      showFileInstalled(`hooks/${filename}`, false, err.message);
+    }
+  }
 }
 
 function registerHooksInSettings() {
@@ -130,6 +141,12 @@ function registerHooksInSettings() {
     hooks:   [{ type: 'command', command: 'node ~/.claude/hooks/hydra-auto-guard.js' }]
   });
 
+  if (!settings.hooks.Notification) settings.hooks.Notification = [];
+  settings.hooks.Notification = settings.hooks.Notification.filter(x => !isHydraHook(x));
+  settings.hooks.Notification.push({
+    hooks: [{ type: 'command', command: 'node ~/.claude/hooks/hydra-notify.js' }]
+  });
+
   let statusLineConfigured = false;
   if (!settings.statusLine || (settings.statusLine.command && settings.statusLine.command.includes('hydra-'))) {
     settings.statusLine = {
@@ -161,6 +178,10 @@ function deregisterHooks() {
       settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(x => !isHydraHook(x));
       if (!settings.hooks.PostToolUse.length) delete settings.hooks.PostToolUse;
     }
+    if (settings.hooks?.Notification) {
+      settings.hooks.Notification = settings.hooks.Notification.filter(x => !isHydraHook(x));
+      if (!settings.hooks.Notification.length) delete settings.hooks.Notification;
+    }
     if (settings.hooks && !Object.keys(settings.hooks).length) delete settings.hooks;
 
     if (settings.statusLine?.command?.includes('hydra-')) delete settings.statusLine;
@@ -305,6 +326,15 @@ async function runUninstall({ interactive = true } = {}) {
     }
   }
 
+  // Remove binary hook files (e.g., .wav)
+  for (const filename of Object.keys(binaryHooks)) {
+    const dest = path.join(GLOBAL_BASE, 'hooks', filename);
+    if (fileExists(dest)) {
+      try { fs.unlinkSync(dest); console.log(chalk.green(`  \u2714 Removed hooks/${filename}`)); }
+      catch (err) { console.log(chalk.red(`  \u2716 Failed: hooks/${filename} \u2014 ${err.message}`)); }
+    }
+  }
+
   // Remove cache file
   const cacheFile = path.join(GLOBAL_BASE, 'cache', 'hydra-update-check.json');
   if (fileExists(cacheFile)) {