agentic-qe 3.7.15 → 3.7.17

package/.claude/agents/v3/qe-devils-advocate.md

@@ -61,6 +61,26 @@ Use up to 7 concurrent strategies per review.
 - **Error Handling Gap Detection**: Find missing error handling for network failures, timeouts, malformed input, and resource exhaustion
 </capabilities>
 
+<adversarial_review_standards>
+### Minimum Finding Requirements
+Every review MUST surface findings meeting a minimum weighted score of 3.0 (severity weights: CRITICAL=3, HIGH=2, MEDIUM=1, LOW=0.5, INFORMATIONAL=0.25).
+
+### Reviewer Mindset
+You are a skeptical reviewer. Your job is to find problems. The LLM agreeability bias works against quality -- actively resist it. Assume the code has defects until proven otherwise.
+
+### Anti-Patterns (NEVER Do These)
+- NEVER produce a review that says "looks good" without at least 3 observations
+- NEVER accept "no findings" without a Clean Justification containing specific evidence
+- NEVER skip the second-pass deep review when initial findings are below minimum
+
+### Clean Justification Protocol
+If the code is genuinely clean (rare), you MUST provide:
+1. List of specific files examined
+2. List of patterns/anti-patterns checked
+3. List of tools/strategies run
+4. Detailed reasoning why no issues were found
+</adversarial_review_standards>
+
 <memory_namespace>
 Reads:
 - aqe/v3/domains/test-generation/results/* - Test generation outputs to challenge

package/.claude/agents/v3/qe-gap-detector.md

@@ -54,8 +54,33 @@ Use up to 6 concurrent analyzers for large codebases.
 - **Test Recommendations**: Prioritized recommendations with effort estimates
 - **Trend Analysis**: Track gap closure over time
 - **Visual Reports**: Gap heatmaps and coverage treemaps
+- **Mechanical Edge Case Mode**: Exhaustive branch enumeration without subjective filtering (BMAD-004)
 </capabilities>
 
+<mechanical_mode>
+## Mechanical/Exhaustive Mode (BMAD-004)
+
+When invoked with `--mechanical` or `--exhaustive` flag, switch to exhaustive branch enumeration mode:
+
+### Exhaustive Mode Behavior
+- Report EVERY unhandled branch path as structured JSON without filtering by risk score
+- No subjective prioritization — purely mechanical enumeration
+- Enumerate: if-without-else, switch-no-default, empty-catch, optional-chaining null paths, promise-no-catch, array-empty-case, logical-or-falsy-trap
+- Output format: UnhandledBranch[] with file, line, column, construct type, trigger condition, current handling, suggested guard
+- Severity is deterministic (based on construct type), not subjective
+
+### Default Mode (unchanged)
+Without the mechanical flag, operate in the standard risk-scored mode with semantic analysis and prioritization.
+
+### Output Formats
+- `--json` — Structured JSON array of UnhandledBranch objects
+- `--table` — Tabular summary grouped by severity
+- `--markdown` — Detailed markdown report with code context
+
+### Implementation
+Uses `src/analysis/branch-enumerator.ts` — a regex-based pattern matcher (no AST parser dependency) that implements the `BranchEnumerator` strategy interface. Detects 13 construct types across TypeScript and JavaScript files.
+</mechanical_mode>
+
 <memory_namespace>
 Reads:
 - aqe/coverage/reports/* - Coverage data (lcov, istanbul, c8)

package/.claude/agents/v3/qe-quality-gate.md

@@ -57,6 +57,14 @@ Use up to 6 concurrent evaluators for complex gates.
 - **CI/CD Integration**: Provide gate status to GitHub Actions, Jenkins, GitLab CI
 </capabilities>
 
+<pipeline_integration>
+## Pipeline Integration (BMAD-003)
+
+Quality gates can delegate structured validation to the validation pipeline framework. When evaluating requirements or documentation quality, invoke the requirements validation pipeline for systematic step-by-step assessment with gate enforcement.
+
+Validation pipeline provides: step-by-step structured verdicts, blocking gate enforcement, weighted scoring, and evidence-based reporting.
+</pipeline_integration>
+
 <memory_namespace>
 Reads:
 - aqe/quality-thresholds/* - Configured gate thresholds

package/.claude/agents/v3/qe-requirements-validator.md

@@ -64,6 +64,31 @@ Use up to 6 concurrent validators.
 - **Quality Gate**: Block untestable requirements from development (score < 50)
 </capabilities>
 
+<structured_validation_pipeline>
+## Structured Validation Pipeline (BMAD-003)
+
+When validating requirements, execute the 13-step validation pipeline:
+
+1. **Format Check** (blocking) — Structure, headings, required sections
+2. **Completeness Check** (blocking) — All required fields populated
+3. **INVEST Criteria** (warning) — Independent, Negotiable, Valuable, Estimable, Small, Testable
+4. **SMART Acceptance** (warning) — Specific, Measurable, Achievable, Relevant, Time-bound
+5. **Testability Score** (warning) — Can each requirement be tested? Score 0-100
+6. **Vague Term Detection** (info) — Flag "should", "might", "various", "etc."
+7. **Information Density** (info) — Every sentence carries weight, no filler
+8. **Traceability Check** (warning) — Requirements to tests mapping exists
+9. **Implementation Leakage** (warning) — Requirements don't prescribe implementation
+10. **Domain Compliance** (info) — Requirements align with domain model
+11. **Dependency Analysis** (info) — Cross-requirement dependencies identified
+12. **BDD Scenario Generation** (warning) — Can generate Given/When/Then for each requirement
+13. **Holistic Quality** (blocking) — Overall coherence, no contradictions
+
+Execute steps in order. Report each step's result before proceeding. Halt at blocking failures unless --continue-on-failure is specified.
+
+### Output Format
+For each step, report: Step name | Status (PASS/FAIL/WARN) | Score (0-100) | Findings count | Evidence summary
+</structured_validation_pipeline>
+
 <memory_namespace>
 Reads:
 - aqe/requirements/* - Requirements documents

package/.claude/agents/v3/subagents/qe-code-reviewer.md

@@ -156,6 +156,17 @@ mcp__agentic-qe__task_submit({
 | 0.0 | Failed: Major issues missed or harmful feedback |
 </learning_protocol>
 
+<minimum_finding_requirements>
+## Minimum Finding Requirements (ADR: BMAD-001)
+
+Every review MUST meet a minimum weighted finding score:
+- Code Review: 3.0
+- Severity weights: CRITICAL=3, HIGH=2, MEDIUM=1, LOW=0.5, INFORMATIONAL=0.25
+- If below minimum after first pass, run deeper analysis with broader scope
+- If genuinely clean, provide Clean Justification with evidence of what was checked
+- Anti-pattern: NEVER say "no issues found" without listing files examined and patterns checked
+</minimum_finding_requirements>
+
 <output_format>
 - JSON for structured review findings
 - Markdown for PR comments

package/.claude/agents/v3/subagents/qe-integration-reviewer.md

@@ -156,6 +156,17 @@ mcp__agentic-qe__task_submit({
 | 0.0 | Failed: Breaking change reached production or consumers not identified |
 </learning_protocol>
 
+<minimum_finding_requirements>
+## Minimum Finding Requirements (ADR: BMAD-001)
+
+Every review MUST meet a minimum weighted finding score:
+- Integration Review: 2.0
+- Severity weights: CRITICAL=3, HIGH=2, MEDIUM=1, LOW=0.5, INFORMATIONAL=0.25
+- If below minimum after first pass, run deeper analysis with broader scope
+- If genuinely clean, provide Clean Justification with evidence of what was checked
+- Anti-pattern: NEVER say "no issues found" without listing files examined and patterns checked
+</minimum_finding_requirements>
+
 <output_format>
 - JSON for structured integration analysis
 - Markdown for integration reports

package/.claude/agents/v3/subagents/qe-performance-reviewer.md

@@ -156,6 +156,17 @@ mcp__agentic-qe__task_submit({
 | 0.0 | Failed: Performance regression reached production |
 </learning_protocol>
 
+<minimum_finding_requirements>
+## Minimum Finding Requirements (ADR: BMAD-001)
+
+Every review MUST meet a minimum weighted finding score:
+- Performance Review: 2.0
+- Severity weights: CRITICAL=3, HIGH=2, MEDIUM=1, LOW=0.5, INFORMATIONAL=0.25
+- If below minimum after first pass, run deeper analysis with broader scope
+- If genuinely clean, provide Clean Justification with evidence of what was checked
+- Anti-pattern: NEVER say "no issues found" without listing files examined and patterns checked
+</minimum_finding_requirements>
+
 <output_format>
 - JSON for structured performance analysis
 - Markdown for performance reports

package/.claude/agents/v3/subagents/qe-security-reviewer.md

@@ -156,6 +156,17 @@ mcp__agentic-qe__task_submit({
 | 0.0 | Failed: Critical vulnerability reached production |
 </learning_protocol>
 
+<minimum_finding_requirements>
+## Minimum Finding Requirements (ADR: BMAD-001)
+
+Every review MUST meet a minimum weighted finding score:
+- Security Review: 3.0
+- Severity weights: CRITICAL=3, HIGH=2, MEDIUM=1, LOW=0.5, INFORMATIONAL=0.25
+- If below minimum after first pass, run deeper analysis with broader scope
+- If genuinely clean, provide Clean Justification with evidence of what was checked
+- Anti-pattern: NEVER say "no issues found" without listing files examined and patterns checked
+</minimum_finding_requirements>
+
 <output_format>
 - JSON for structured vulnerability reports
 - Markdown for security advisories

package/.claude/helpers/adr-compliance.sh

@@ -41,7 +41,7 @@ check_adr_001() {
   grep -q "agentic-flow" "$PROJECT_ROOT/package.json" 2>/dev/null && score=$((score + 50))
 
   # Check for imports from agentic-flow
-  local imports=$(grep -r "from.*agentic-flow\|require.*agentic-flow" "$PROJECT_ROOT/src" 2>/dev/null | grep -v node_modules | wc -l)
+  local imports=$(grep -r "from.*agentic-flow\|require.*agentic-flow" "$PROJECT_ROOT/v3" "$PROJECT_ROOT/src" 2>/dev/null | grep -v node_modules | wc -l)
   [ "$imports" -gt 5 ] && score=$((score + 50))
 
   echo "$score"
@@ -52,14 +52,14 @@ check_adr_002() {
   local score=0
 
   # Check for domain directories
-  [ -d "$PROJECT_ROOT/src/domains" ] && score=$((score + 30))
+  [ -d "$PROJECT_ROOT/v3" ] || [ -d "$PROJECT_ROOT/src/domains" ] && score=$((score + 30))
 
   # Check for bounded contexts
-  local contexts=$(find "$PROJECT_ROOT/src" -type d -name "domain" 2>/dev/null | wc -l)
+  local contexts=$(find "$PROJECT_ROOT/v3" "$PROJECT_ROOT/src" -type d -name "domain" 2>/dev/null | wc -l)
   [ "$contexts" -gt 0 ] && score=$((score + 35))
 
   # Check for anti-corruption layers
-  local acl=$(grep -r "AntiCorruption\|Adapter\|Port" "$PROJECT_ROOT/src" 2>/dev/null | grep -v node_modules | wc -l)
+  local acl=$(grep -r "AntiCorruption\|Adapter\|Port" "$PROJECT_ROOT/v3" "$PROJECT_ROOT/src" 2>/dev/null | grep -v node_modules | wc -l)
   [ "$acl" -gt 0 ] && score=$((score + 35))
 
   echo "$score"
@@ -70,10 +70,10 @@ check_adr_003() {
   local score=0
 
   # Check for unified SwarmCoordinator
-  grep -rq "SwarmCoordinator\|UnifiedCoordinator" "$PROJECT_ROOT/src" 2>/dev/null && score=$((score + 50))
+  grep -rq "SwarmCoordinator\|UnifiedCoordinator" "$PROJECT_ROOT/v3" "$PROJECT_ROOT/src" 2>/dev/null && score=$((score + 50))
 
   # Check for no duplicate coordinators
-  local coordinators=$(grep -r "class.*Coordinator" "$PROJECT_ROOT/src" 2>/dev/null | grep -v node_modules | grep -v ".test." | wc -l)
+  local coordinators=$(grep -r "class.*Coordinator" "$PROJECT_ROOT/v3" "$PROJECT_ROOT/src" 2>/dev/null | grep -v node_modules | grep -v ".test." | wc -l)
   [ "$coordinators" -le 3 ] && score=$((score + 50))
 
   echo "$score"
@@ -84,14 +84,14 @@ check_adr_005() {
   local score=0
 
   # Check for MCP server implementation
-  [ -d "$PROJECT_ROOT/src/mcp" ] && score=$((score + 40))
+  [ -d "$PROJECT_ROOT/v3/@claude-flow/mcp" ] && score=$((score + 40))
 
   # Check for MCP tools
-  local tools=$(grep -r "tool.*name\|registerTool" "$PROJECT_ROOT/src" 2>/dev/null | wc -l)
+  local tools=$(grep -r "tool.*name\|registerTool" "$PROJECT_ROOT/v3" 2>/dev/null | wc -l)
   [ "$tools" -gt 5 ] && score=$((score + 30))
 
   # Check for MCP schemas
-  grep -rq "schema\|jsonSchema" "$PROJECT_ROOT/src/mcp" 2>/dev/null && score=$((score + 30))
+  grep -rq "schema\|jsonSchema" "$PROJECT_ROOT/v3/@claude-flow/mcp" 2>/dev/null && score=$((score + 30))
 
   echo "$score"
 }
@@ -104,7 +104,7 @@ check_adr_008() {
   grep -q "vitest" "$PROJECT_ROOT/package.json" 2>/dev/null && score=$((score + 50))
 
   # Check for no jest references
-  local jest_refs=$(grep -r "from.*jest\|jest\." "$PROJECT_ROOT/src" 2>/dev/null | grep -v node_modules | grep -v "vitest" | wc -l)
+  local jest_refs=$(grep -r "from.*jest\|jest\." "$PROJECT_ROOT/v3" "$PROJECT_ROOT/src" 2>/dev/null | grep -v node_modules | grep -v "vitest" | wc -l)
   [ "$jest_refs" -eq 0 ] && score=$((score + 50))
 
   echo "$score"

package/.claude/helpers/auto-memory-hook.mjs

@@ -139,17 +139,30 @@ async function loadMemoryPackage() {
     } catch { /* fall through */ }
   }
 
-  // Strategy 2: npm installed @claude-flow/memory
+  // Strategy 2: Use createRequire for CJS-style resolution (handles nested node_modules
+  // when installed as a transitive dependency via npx ruflo / npx claude-flow)
+  try {
+    const { createRequire } = await import('module');
+    const require = createRequire(join(PROJECT_ROOT, 'package.json'));
+    return require('@claude-flow/memory');
+  } catch { /* fall through */ }
+
+  // Strategy 3: ESM import (works when @claude-flow/memory is a direct dependency)
   try {
     return await import('@claude-flow/memory');
   } catch { /* fall through */ }
 
-  // Strategy 3: Installed via @claude-flow/cli which includes memory
-  const cliMemory = join(PROJECT_ROOT, 'node_modules/@claude-flow/memory/dist/index.js');
-  if (existsSync(cliMemory)) {
-    try {
-      return await import(`file://${cliMemory}`);
-    } catch { /* fall through */ }
+  // Strategy 4: Walk up from PROJECT_ROOT looking for @claude-flow/memory in any node_modules
+  let searchDir = PROJECT_ROOT;
+  const { parse } = await import('path');
+  while (searchDir !== parse(searchDir).root) {
+    const candidate = join(searchDir, 'node_modules', '@claude-flow', 'memory', 'dist', 'index.js');
+    if (existsSync(candidate)) {
+      try {
+        return await import(`file://${candidate}`);
+      } catch { /* fall through */ }
+    }
+    searchDir = dirname(searchDir);
   }
 
   return null;
@@ -342,9 +355,11 @@ try {
     case 'status': await doStatus(); break;
     default:
       console.log('Usage: auto-memory-hook.mjs <import|sync|status>');
-      process.exit(1);
+      break;
   }
 } catch (err) {
   // Hooks must never crash Claude Code - fail silently
-  dim(`Error (non-critical): ${err.message}`);
+  try { dim(`Error (non-critical): ${err.message}`); } catch (_) {}
 }
+// Hooks must ALWAYS exit 0
+process.exitCode = 0;

package/.claude/helpers/brain-checkpoint.cjs

@@ -1,134 +1,55 @@
-#!/usr/bin/env node
-/**
- * Brain Checkpoint Helper
- *
- * Automatic brain export/verify for session hooks.
- *
- * Usage:
- *   node brain-checkpoint.cjs export   # Export brain to aqe.rvf (session-end)
- *   node brain-checkpoint.cjs verify   # Verify aqe.rvf exists and is recent (session-start)
- *   node brain-checkpoint.cjs info     # Show aqe.rvf info
- *
- * Called from .claude/settings.json Stop and SessionStart hooks.
- */
-
-const { execSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-
-const AQE_DIR = path.join(process.cwd(), '.agentic-qe');
-const RVF_PATH = path.join(AQE_DIR, 'aqe.rvf');
-const DB_PATH = path.join(AQE_DIR, 'memory.db');
-const CLI = path.join(process.cwd(), 'dist', 'cli', 'bundle.js');
-const MAX_AGE_HOURS = 24;
-
-function log(msg) {
-  process.stderr.write(`[brain-checkpoint] ${msg}\n`);
-}
-
-function exportBrain() {
-  if (!fs.existsSync(DB_PATH)) {
-    log('No memory.db found, skipping export');
-    return { exported: false, reason: 'no-db' };
-  }
-
-  if (!fs.existsSync(CLI)) {
-    log('CLI bundle not found, skipping export');
-    return { exported: false, reason: 'no-cli' };
-  }
-
-  try {
-    // Remove existing to avoid LockHeld errors
-    if (fs.existsSync(RVF_PATH)) {
-      fs.unlinkSync(RVF_PATH);
-    }
-    const idmap = `${RVF_PATH}.idmap.json`;
-    if (fs.existsSync(idmap)) {
-      fs.unlinkSync(idmap);
-    }
-
-    const result = execSync(
-      `node "${CLI}" brain export -o "${RVF_PATH}" --format rvf 2>&1`,
-      { timeout: 60000, encoding: 'utf-8' }
-    );
-
-    const sizeMatch = result.match(/RVF Size:\s+(.+)/);
-    const patternsMatch = result.match(/Patterns:\s+(\d+)/);
-    const size = sizeMatch ? sizeMatch[1].trim() : 'unknown';
-    const patterns = patternsMatch ? patternsMatch[1] : '0';
-
-    log(`Exported ${patterns} patterns (${size}) to aqe.rvf`);
-    return { exported: true, patterns: parseInt(patterns), size };
-  } catch (e) {
-    log(`Export failed: ${e.message}`);
-    return { exported: false, reason: e.message };
-  }
-}
-
-function verifyBrain() {
-  if (!fs.existsSync(RVF_PATH)) {
-    log('No aqe.rvf found — brain checkpoint missing');
-    return { valid: false, reason: 'missing' };
-  }
-
-  const stat = fs.statSync(RVF_PATH);
-  const ageHours = (Date.now() - stat.mtimeMs) / (1000 * 60 * 60);
-
-  if (stat.size < 1024) {
-    log('aqe.rvf is too small — likely corrupt');
-    return { valid: false, reason: 'too-small', sizeBytes: stat.size };
-  }
-
-  if (ageHours > MAX_AGE_HOURS) {
-    log(`aqe.rvf is ${ageHours.toFixed(1)}h old — consider re-exporting`);
-    return { valid: true, stale: true, ageHours: Math.round(ageHours) };
-  }
-
-  log(`aqe.rvf OK (${(stat.size / 1024 / 1024).toFixed(1)} MB, ${ageHours.toFixed(1)}h old)`);
-  return { valid: true, stale: false, ageHours: Math.round(ageHours), sizeBytes: stat.size };
-}
-
-function infoBrain() {
-  if (!fs.existsSync(RVF_PATH)) {
-    log('No aqe.rvf found');
-    return { exists: false };
-  }
-
-  if (!fs.existsSync(CLI)) {
-    const stat = fs.statSync(RVF_PATH);
-    return { exists: true, sizeBytes: stat.size, modified: stat.mtime.toISOString() };
-  }
-
-  try {
-    const result = execSync(
-      `node "${CLI}" brain info -i "${RVF_PATH}" 2>&1`,
-      { timeout: 15000, encoding: 'utf-8' }
-    );
-    return { exists: true, info: result.trim() };
-  } catch (e) {
-    return { exists: true, error: e.message };
-  }
-}
-
-// Main
-const command = process.argv[2] || 'verify';
-let result;
-
-switch (command) {
-  case 'export':
-    result = exportBrain();
-    break;
-  case 'verify':
-    result = verifyBrain();
-    break;
-  case 'info':
-    result = infoBrain();
-    break;
-  default:
-    log(`Unknown command: ${command}`);
-    process.exit(1);
-}
-
-if (process.argv.includes('--json')) {
-  process.stdout.write(JSON.stringify(result));
-}
+#!/usr/bin/env node
+/**
+ * Brain Checkpoint Helper (generated by aqe init)
+ *
+ * Usage:
+ *   node brain-checkpoint.cjs export   # Export brain to aqe.rvf (session-end)
+ *   node brain-checkpoint.cjs verify   # Verify aqe.rvf exists (session-start)
+ */
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const AQE_DIR = path.join(process.cwd(), '.agentic-qe');
+const RVF_PATH = path.join(AQE_DIR, 'aqe.rvf');
+const DB_PATH = path.join(AQE_DIR, 'memory.db');
+const MAX_AGE_HOURS = 24;
+
+function log(msg) { process.stderr.write('[brain-checkpoint] ' + msg + '\n'); }
+
+function exportBrain() {
+  if (!fs.existsSync(DB_PATH)) { log('No memory.db, skipping'); return { exported: false }; }
+  try {
+    if (fs.existsSync(RVF_PATH)) fs.unlinkSync(RVF_PATH);
+    const idmap = RVF_PATH + '.idmap.json';
+    if (fs.existsSync(idmap)) fs.unlinkSync(idmap);
+    const result = execSync(
+      'npx agentic-qe brain export -o "' + RVF_PATH + '" --format rvf 2>&1',
+      { timeout: 60000, encoding: 'utf-8' }
+    );
+    const m = result.match(/Patterns:\s+(\d+)/);
+    const p = m ? m[1] : '0';
+    log('Exported ' + p + ' patterns to aqe.rvf');
+    return { exported: true, patterns: parseInt(p) };
+  } catch (e) {
+    log('Export failed: ' + e.message);
+    return { exported: false, reason: e.message };
+  }
+}
+
+function verifyBrain() {
+  if (!fs.existsSync(RVF_PATH)) {
+    log('No aqe.rvf found');
+    return { valid: false, reason: 'missing' };
+  }
+  const stat = fs.statSync(RVF_PATH);
+  const ageH = (Date.now() - stat.mtimeMs) / 3600000;
+  if (stat.size < 1024) { log('aqe.rvf too small'); return { valid: false, reason: 'too-small' }; }
+  if (ageH > MAX_AGE_HOURS) { log('aqe.rvf is ' + ageH.toFixed(1) + 'h old'); return { valid: true, stale: true }; }
+  log('aqe.rvf OK (' + (stat.size/1048576).toFixed(1) + ' MB)');
+  return { valid: true, stale: false };
+}
+
+const cmd = process.argv[2] || 'verify';
+const result = cmd === 'export' ? exportBrain() : verifyBrain();
+if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result));

package/.claude/helpers/ddd-tracker.sh

@@ -25,7 +25,7 @@ should_run() {
 
 check_domain() {
   local domain="$1"
-  local domain_path="$PROJECT_ROOT/src/domains/$domain"
+  local domain_path="$PROJECT_ROOT/v3/@claude-flow/$domain"
   local alt_path="$PROJECT_ROOT/src/domains/$domain"
 
   local score=0
@@ -64,7 +64,7 @@ count_entities() {
   local type="$1"
   local pattern="$2"
 
-  find "$PROJECT_ROOT/src" -name "*.ts" 2>/dev/null | \
+  find "$PROJECT_ROOT/v3" "$PROJECT_ROOT/src" -name "*.ts" 2>/dev/null | \
     xargs grep -l "$pattern" 2>/dev/null | \
     grep -v node_modules | grep -v ".test." | wc -l || echo "0"
 }

package/.claude/helpers/guidance-hooks.sh

@@ -28,8 +28,8 @@ case "$COMMAND" in
             if [[ "$FILE_PATH" =~ (config|secret|credential|password|key|auth) ]]; then
                 echo -e "${YELLOW}[Guidance] Security-sensitive file${RESET}"
             fi
-            if [[ "$FILE_PATH" =~ ^src/ ]]; then
-                echo -e "${CYAN}[Guidance] Source module - follow ADR guidelines${RESET}"
+            if [[ "$FILE_PATH" =~ ^v3/ ]]; then
+                echo -e "${CYAN}[Guidance] V3 module - follow ADR guidelines${RESET}"
             fi
         fi
         exit 0

package/.claude/helpers/hook-handler.cjs

@@ -50,8 +50,37 @@ const intelligence = safeRequire(path.join(helpersDir, 'intelligence.cjs'));
 // Get the command from argv
 const [,, command, ...args] = process.argv;
 
-// Get prompt from environment variable (set by Claude Code hooks)
-const prompt = process.env.PROMPT || process.env.TOOL_INPUT_command || args.join(' ') || '';
+// Read stdin with timeout — Claude Code sends hook data as JSON via stdin.
+// Timeout prevents hanging when stdin is not properly closed (common on Windows).
+async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  return new Promise((resolve) => {
+    let data = '';
+    const timer = setTimeout(() => {
+      process.stdin.removeAllListeners();
+      process.stdin.pause();
+      resolve(data);
+    }, 500);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => { clearTimeout(timer); resolve(data); });
+    process.stdin.on('error', () => { clearTimeout(timer); resolve(data); });
+    process.stdin.resume();
+  });
+}
+
+async function main() {
+  let stdinData = '';
+  try { stdinData = await readStdin(); } catch (e) { /* ignore stdin errors */ }
+
+  let hookInput = {};
+  if (stdinData.trim()) {
+    try { hookInput = JSON.parse(stdinData); } catch (e) { /* ignore parse errors */ }
+  }
+
+  // Merge stdin data into prompt resolution: prefer stdin fields, then env, then argv
+  const prompt = hookInput.prompt || hookInput.command || hookInput.toolInput
+    || process.env.PROMPT || process.env.TOOL_INPUT_command || args.join(' ') || '';
 
 const handlers = {
   'route': () => {
@@ -105,8 +134,8 @@ const handlers = {
   },
 
   'pre-bash': () => {
-    // Basic command safety check
-    const cmd = prompt.toLowerCase();
+    // Basic command safety check — prefer stdin command data from Claude Code
+    const cmd = (hookInput.command || prompt).toLowerCase();
     const dangerous = ['rm -rf /', 'format c:', 'del /s /q c:\\', ':(){:|:&};:'];
     for (const d of dangerous) {
       if (cmd.includes(d)) {
@@ -122,10 +151,11 @@ const handlers = {
     if (session && session.metric) {
       try { session.metric('edits'); } catch (e) { /* no active session */ }
     }
-    // Record edit for intelligence consolidation
+    // Record edit for intelligence consolidation — prefer stdin data from Claude Code
     if (intelligence && intelligence.recordEdit) {
       try {
-        const file = process.env.TOOL_INPUT_file_path || args[0] || '';
+        const file = hookInput.file_path || (hookInput.toolInput && hookInput.toolInput.file_path)
+          || process.env.TOOL_INPUT_file_path || args[0] || '';
         intelligence.recordEdit(file);
       } catch (e) { /* non-fatal */ }
     }
@@ -216,17 +246,26 @@ const handlers = {
   },
 };
 
-// Execute the handler
-if (command && handlers[command]) {
-  try {
-    handlers[command]();
-  } catch (e) {
-    // Hooks should never crash Claude Code - fail silently
-    console.log(`[WARN] Hook ${command} encountered an error: ${e.message}`);
+  // Execute the handler
+  if (command && handlers[command]) {
+    try {
+      handlers[command]();
+    } catch (e) {
+      // Hooks should never crash Claude Code - fail silently
+      console.log(`[WARN] Hook ${command} encountered an error: ${e.message}`);
+    }
+  } else if (command) {
+    // Unknown command - pass through without error
+    console.log(`[OK] Hook: ${command}`);
+  } else {
+    console.log('Usage: hook-handler.cjs <route|pre-bash|post-edit|session-restore|session-end|pre-task|post-task|stats>');
   }
-} else if (command) {
-  // Unknown command - pass through without error
-  console.log(`[OK] Hook: ${command}`);
-} else {
-  console.log('Usage: hook-handler.cjs <route|pre-bash|post-edit|session-restore|session-end|pre-task|post-task|stats>');
 }
+
+// Hooks must ALWAYS exit 0 — Claude Code treats non-zero as "hook error"
+// and skips all subsequent hooks for the event.
+process.exitCode = 0;
+main().catch((e) => {
+  try { console.log(`[WARN] Hook handler error: ${e.message}`); } catch (_) {}
+  process.exitCode = 0;
+});