@qball-inc/the-bulwark 1.0.0

package/scripts/hooks/implementer-quality.sh

@@ -0,0 +1,256 @@
+#!/bin/bash
+# implementer-quality.sh - Agent-invoked quality gate + pipeline suggestion
+#
+# Called by bulwark-implementer agent directly via Bash after each Write/Edit.
+# Unlike enforce-quality.sh (which reads stdin JSON from hook system),
+# this script accepts a file path as a CLI argument.
+#
+# Phase 1: Quality checks (code files only)
+#   - Runs just typecheck, lint, build
+#   - Outputs error details to stdout on failure
+#
+# Phase 2: Pipeline suggestion (all file types)
+#   - Classifies file type and estimates change size
+#   - Outputs plain text suggestion
+#
+# Exit codes:
+#   0 = All checks passed (or non-code file)
+#   1 = Quality gate failed
+#
+# Usage: implementer-quality.sh <file_path>
+
+set -euo pipefail
+
+# Configuration
+MAX_OUTPUT_LINES=100
+
+# Validate arguments
+if [ $# -lt 1 ]; then
+    echo "ERROR: Missing file path argument" >&2
+    echo "Usage: implementer-quality.sh <file_path>" >&2
+    exit 1
+fi
+
+FILE_PATH="$1"
+
+# Get directories
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+LOGS_DIR="${PROJECT_DIR}/logs"
+HOOKS_LOG="${LOGS_DIR}/hooks.log"
+
+# Ensure logs directory exists
+mkdir -p "$LOGS_DIR"
+
+# Log invocation
+TIMESTAMP=$(date -Iseconds)
+echo "[$TIMESTAMP] implementer-quality.sh invoked for ${FILE_PATH}" >> "$HOOKS_LOG"
+
+# Skip infrastructure directories
+case "$FILE_PATH" in
+    */logs/*|logs/*|*/tmp/*|tmp/*|*/.claude/*|.claude/*|*/node_modules/*|node_modules/*)
+        echo "QUALITY: SKIPPED (infrastructure path)"
+        exit 0
+        ;;
+esac
+
+# Function to detect if file is a code file
+is_code_file() {
+    local path="$1"
+    echo "$path" | grep -qiE '\.(ts|js|tsx|jsx|py|go|rs|java|cpp|c|rb|php|swift|kt)$'
+}
+
+# Function to find just command
+find_just() {
+    if command -v just &> /dev/null; then
+        echo "just"
+    elif [ -x "$HOME/.local/bin/just" ]; then
+        echo "$HOME/.local/bin/just"
+    elif [ -x "/usr/local/bin/just" ]; then
+        echo "/usr/local/bin/just"
+    else
+        echo ""
+    fi
+}
+
+# Function to check if a Justfile recipe exists
+recipe_exists() {
+    local recipe="$1"
+    local just_cmd="$2"
+    $just_cmd --list 2>/dev/null | grep -qE "^${recipe}[[:space:]]" || \
+    $just_cmd --list 2>/dev/null | grep -qE "^${recipe}$"
+}
+
+# ============================================================
+# PHASE 1: Quality Checks (code files only)
+# ============================================================
+
+QUALITY_PASSED="true"
+
+if is_code_file "$FILE_PATH"; then
+    if [ ! -f "${PROJECT_DIR}/Justfile" ]; then
+        echo "WARNING: No Justfile found. Quality checks skipped."
+    else
+        JUST_CMD=$(find_just)
+
+        if [ -z "$JUST_CMD" ]; then
+            echo "WARNING: just command not found. Quality checks skipped."
+        else
+            cd "${PROJECT_DIR}"
+
+            # Run typecheck if recipe exists
+            if recipe_exists "typecheck" "$JUST_CMD"; then
+                TYPECHECK_OUTPUT=$($JUST_CMD typecheck 2>&1 | head -n $MAX_OUTPUT_LINES) || {
+                    QUALITY_PASSED="false"
+                    echo "QUALITY: FAILED"
+                    echo "GATE: typecheck"
+                    echo "---"
+                    echo "$TYPECHECK_OUTPUT"
+                    echo "---"
+                    echo "Fix the type errors above and retry."
+                    echo "[$TIMESTAMP] implementer-quality.sh: FAILED typecheck for ${FILE_PATH}" >> "$HOOKS_LOG"
+                    exit 1
+                }
+            fi
+
+            # Run lint if recipe exists
+            if recipe_exists "lint" "$JUST_CMD"; then
+                LINT_OUTPUT=$($JUST_CMD lint 2>&1 | head -n $MAX_OUTPUT_LINES) || {
+                    QUALITY_PASSED="false"
+                    echo "QUALITY: FAILED"
+                    echo "GATE: lint"
+                    echo "---"
+                    echo "$LINT_OUTPUT"
+                    echo "---"
+                    echo "Fix the lint errors above and retry."
+                    echo "[$TIMESTAMP] implementer-quality.sh: FAILED lint for ${FILE_PATH}" >> "$HOOKS_LOG"
+                    exit 1
+                }
+            fi
+
+            # Run build if recipe exists
+            if recipe_exists "build" "$JUST_CMD"; then
+                BUILD_OUTPUT=$($JUST_CMD build 2>&1 | head -n $MAX_OUTPUT_LINES) || {
+                    QUALITY_PASSED="false"
+                    echo "QUALITY: FAILED"
+                    echo "GATE: build"
+                    echo "---"
+                    echo "$BUILD_OUTPUT"
+                    echo "---"
+                    echo "Fix the build errors above and retry."
+                    echo "[$TIMESTAMP] implementer-quality.sh: FAILED build for ${FILE_PATH}" >> "$HOOKS_LOG"
+                    exit 1
+                }
+            fi
+        fi
+    fi
+fi
+
+# ============================================================
+# PHASE 2: Pipeline Suggestion (all file types)
+# ============================================================
+
+# Extract file extension and name
+FILENAME=$(basename "$FILE_PATH")
+EXTENSION="${FILENAME##*.}"
+EXTENSION_LOWER=$(echo "$EXTENSION" | tr '[:upper:]' '[:lower:]')
+
+# Determine file type
+IS_CODE="false"
+IS_TEST="false"
+IS_CONFIG="false"
+IS_DOC="false"
+IS_SCRIPT="false"
+IS_DATA="false"
+
+# Code files
+if echo "$EXTENSION_LOWER" | grep -qE '^(ts|js|tsx|jsx|py|go|rs|java|cpp|c|rb|php|swift|kt)$'; then
+    IS_CODE="true"
+fi
+
+# Test files (check filename pattern)
+if echo "$FILENAME" | grep -qiE '(test|spec|_test)\.(ts|js|tsx|jsx|py|go|rs|java|cpp|rb)$'; then
+    IS_TEST="true"
+    IS_CODE="false"
+fi
+
+# Config files
+if echo "$EXTENSION_LOWER" | grep -qE '^(json|yaml|yml|toml|ini|env|config)$'; then
+    IS_CONFIG="true"
+fi
+
+# Documentation files
+if echo "$EXTENSION_LOWER" | grep -qE '^(md|txt|rst|adoc)$'; then
+    IS_DOC="true"
+fi
+
+# Script files
+if echo "$EXTENSION_LOWER" | grep -qE '^(sh|bash|zsh|fish|ps1)$'; then
+    IS_SCRIPT="true"
+fi
+
+# Data files
+if echo "$EXTENSION_LOWER" | grep -qE '^(xlsx|xls|csv|pdf|docx|pptx)$'; then
+    IS_DATA="true"
+fi
+
+# Count file lines as change size proxy (no hook JSON available)
+if [ -f "$FILE_PATH" ]; then
+    CHANGE_SIZE=$(wc -l < "$FILE_PATH" 2>/dev/null || echo "0")
+else
+    CHANGE_SIZE=0
+fi
+
+# Determine threshold based on file type
+THRESHOLD=5
+if [ "$IS_TEST" = "true" ]; then
+    THRESHOLD=10
+elif [ "$IS_CONFIG" = "true" ]; then
+    THRESHOLD=3
+elif [ "$IS_DOC" = "true" ]; then
+    THRESHOLD=10
+elif [ "$IS_SCRIPT" = "true" ]; then
+    THRESHOLD=3
+elif [ "$IS_DATA" = "true" ]; then
+    THRESHOLD=1
+fi
+
+# Determine recommended pipeline
+RECOMMENDED_PIPELINE="none"
+if [ "$CHANGE_SIZE" -gt "$THRESHOLD" ]; then
+    if [ "$IS_CODE" = "true" ]; then
+        # Check if file already existed (Edit vs new Write)
+        # Since we can't tell from CLI, use line count as heuristic:
+        # large files are likely existing code, small files may be new
+        RECOMMENDED_PIPELINE="Code Review"
+    elif [ "$IS_TEST" = "true" ]; then
+        RECOMMENDED_PIPELINE="Test Audit"
+    elif [ "$IS_CONFIG" = "true" ]; then
+        RECOMMENDED_PIPELINE="Code Review"
+    elif [ "$IS_SCRIPT" = "true" ]; then
+        RECOMMENDED_PIPELINE="Code Review"
+    elif [ "$IS_DOC" = "true" ]; then
+        RECOMMENDED_PIPELINE="none"
+    elif [ "$IS_DATA" = "true" ]; then
+        RECOMMENDED_PIPELINE="none"
+    fi
+fi
+
+# Log decision
+echo "[$TIMESTAMP] implementer-quality.sh: PASSED for ${FILE_PATH} (pipeline: ${RECOMMENDED_PIPELINE}, lines: ${CHANGE_SIZE})" >> "$HOOKS_LOG"
+
+# Output results in plain text format
+echo "QUALITY: PASSED"
+echo "PIPELINE: ${RECOMMENDED_PIPELINE}"
+echo "TARGET: ${FILE_PATH}"
+echo "LINES: ${CHANGE_SIZE}"
+if [ "$RECOMMENDED_PIPELINE" != "none" ]; then
+    echo "REASON: File type detected, ${CHANGE_SIZE} lines exceeds threshold ${THRESHOLD}"
+    echo "ACTION: Load pipeline-templates skill to execute this pipeline"
+else
+    if [ "$CHANGE_SIZE" -le "$THRESHOLD" ]; then
+        echo "REASON: Small change (${CHANGE_SIZE} lines, threshold ${THRESHOLD}), no pipeline needed"
+    else
+        echo "REASON: File type does not require pipeline review"
+    fi
+fi

package/scripts/hooks/inject-protocol.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# inject-protocol.sh - Inject governance protocol at session start
+#
+# Hook configuration: once: true (fires once per session)
+# Exit code 0: stdout added to Claude's CONTEXT (not just verbose mode)
+#
+# Architecture: Reads governance content from skill file (not hardcoded)
+# This keeps governance readable and user-extensible.
+#
+# Usage: Called by SessionStart hook, not directly by users
+
+set -euo pipefail
+
+# Get directories
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+LOGS_DIR="${PROJECT_DIR}/logs"
+HOOKS_LOG="${LOGS_DIR}/hooks.log"
+
+# Skill file location (relative to script in plugin structure)
+# Script is at: scripts/hooks/inject-protocol.sh
+# Skill is at:  skills/governance-protocol/SKILL.md
+SKILL_FILE="${SCRIPT_DIR}/../../skills/governance-protocol/SKILL.md"
+
+# Ensure logs directory exists
+mkdir -p "$LOGS_DIR"
+
+# Log the injection event (for verification)
+TIMESTAMP=$(date -Iseconds)
+echo "[${TIMESTAMP}] SessionStart: Governance protocol injected (once:true)" >> "$HOOKS_LOG"
+
+# Output activation header (visible in Claude's context)
+echo "═══════════════════════════════════════════════════════════════"
+echo "  BULWARK GOVERNANCE PROTOCOL - ACTIVATED"
+echo "  Quality enforcement enabled for this session"
+echo "═══════════════════════════════════════════════════════════════"
+echo ""
+
+# Extract and output skill content (after frontmatter)
+# Frontmatter is between first --- and second ---
+if [ -f "$SKILL_FILE" ]; then
+  # Use awk with state tracking to skip frontmatter
+  # Handle both Unix (LF) and Windows (CRLF) line endings
+  awk 'BEGIN{s=0} /^---\r?$/{s++;next} s>=2{gsub(/\r$/,"");print}' "$SKILL_FILE"
+else
+  echo "Warning: governance-protocol skill not found at ${SKILL_FILE}" >&2
+  echo "## Bulwark Governance Protocol"
+  echo ""
+  echo "Governance skill not found. Please ensure skills/governance-protocol/SKILL.md exists."
+fi
+
+exit 0

package/scripts/hooks/suggest-pipeline.sh

@@ -0,0 +1,175 @@
+#!/bin/bash
+# suggest-pipeline.sh
+# PostToolUse hook for Write|Edit - suggests pipeline orchestration after code changes
+#
+# Input (stdin): JSON with tool_name, tool_input, tool_response
+# Output (stdout): JSON with hookSpecificOutput.additionalContext
+#
+# Behavior:
+# - Small changes: Skip silently (no suggestion)
+# - Significant changes: Inject additionalContext instructing Claude to load pipeline-templates
+#
+# Small Change Thresholds:
+# - Code files: < 5 lines
+# - Test files: < 10 lines
+# - Config files: < 3 lines
+# - Documentation: <= 10 lines
+# - Scripts: < 3 lines
+#
+# PRODUCTION MODE:
+# - Hook is always enabled (no flag file check)
+# - Configured via /bulwark-scaffold (--no-hooks to opt out)
+# - Called by enforce-quality.sh after quality checks pass
+
+# Ensure logs directory exists
+LOGS_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}/logs"
+mkdir -p "$LOGS_DIR"
+
+# Read input from stdin
+INPUT=$(cat)
+
+# Parse tool details
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Skip infrastructure directories (no quality checks or pipeline suggestions)
+# DEF-005: Prevents infinite loops when writing to logs/
+case "$FILE_PATH" in
+  */logs/*|logs/*|*/tmp/*|tmp/*|*/.claude/*|.claude/*|*/node_modules/*|node_modules/*)
+    exit 0
+    ;;
+esac
+
+# Log the invocation
+echo "[$TIMESTAMP] PostToolUse: $TOOL_NAME on $FILE_PATH" >> "$LOGS_DIR/hooks.log"
+
+# Extract file extension and name
+FILENAME=$(basename "$FILE_PATH")
+EXTENSION="${FILENAME##*.}"
+EXTENSION_LOWER=$(echo "$EXTENSION" | tr '[:upper:]' '[:lower:]')
+
+# Determine file type
+IS_CODE="false"
+IS_TEST="false"
+IS_CONFIG="false"
+IS_DOC="false"
+IS_SCRIPT="false"
+IS_DATA="false"
+
+# Code files
+if echo "$EXTENSION_LOWER" | grep -qE '^(ts|js|tsx|jsx|py|go|rs|java|cpp|c|rb|php|swift|kt)$'; then
+  IS_CODE="true"
+fi
+
+# Test files (check filename pattern)
+if echo "$FILENAME" | grep -qiE '(test|spec|_test)\.(ts|js|tsx|jsx|py|go|rs|java|cpp|rb)$'; then
+  IS_TEST="true"
+  IS_CODE="false"  # Treat as test, not code
+fi
+
+# Config files
+if echo "$EXTENSION_LOWER" | grep -qE '^(json|yaml|yml|toml|ini|env|config)$'; then
+  IS_CONFIG="true"
+fi
+
+# Documentation files
+if echo "$EXTENSION_LOWER" | grep -qE '^(md|txt|rst|adoc)$'; then
+  IS_DOC="true"
+fi
+
+# Script files
+if echo "$EXTENSION_LOWER" | grep -qE '^(sh|bash|zsh|fish|ps1)$'; then
+  IS_SCRIPT="true"
+fi
+
+# Data files
+if echo "$EXTENSION_LOWER" | grep -qE '^(xlsx|xls|csv|pdf|docx|pptx)$'; then
+  IS_DATA="true"
+fi
+
+# Calculate change size
+if [ "$TOOL_NAME" = "Edit" ]; then
+  # For Edit, measure the old_string and new_string
+  OLD_LINES=$(echo "$INPUT" | jq -r '.tool_input.old_string // ""' | wc -l)
+  NEW_LINES=$(echo "$INPUT" | jq -r '.tool_input.new_string // ""' | wc -l)
+  CHANGE_SIZE=$((NEW_LINES > OLD_LINES ? NEW_LINES : OLD_LINES))
+else
+  # For Write, use content length
+  CHANGE_SIZE=$(echo "$INPUT" | jq -r '.tool_input.content // ""' | wc -l)
+fi
+
+# Determine threshold based on file type
+THRESHOLD=5  # Default for code
+if [ "$IS_TEST" = "true" ]; then
+  THRESHOLD=10
+elif [ "$IS_CONFIG" = "true" ]; then
+  THRESHOLD=3
+elif [ "$IS_DOC" = "true" ]; then
+  THRESHOLD=10
+elif [ "$IS_SCRIPT" = "true" ]; then
+  THRESHOLD=3
+elif [ "$IS_DATA" = "true" ]; then
+  THRESHOLD=1  # Any data file change is significant
+fi
+
+# Log decision factors
+echo "[$TIMESTAMP] File type: code=$IS_CODE test=$IS_TEST config=$IS_CONFIG doc=$IS_DOC script=$IS_SCRIPT data=$IS_DATA" >> "$LOGS_DIR/hooks.log"
+echo "[$TIMESTAMP] Change size: $CHANGE_SIZE lines, threshold: $THRESHOLD" >> "$LOGS_DIR/hooks.log"
+
+# Skip small changes
+if [ "$CHANGE_SIZE" -le "$THRESHOLD" ]; then
+  echo "[$TIMESTAMP] Pipeline: SKIP (small change: $CHANGE_SIZE <= $THRESHOLD)" >> "$LOGS_DIR/hooks.log"
+  exit 0
+fi
+
+# Determine recommended pipeline based on file type AND work type
+# DEF-004: Write (new file) vs Edit (existing file) affects pipeline selection
+RECOMMENDED_PIPELINE="Code Review"
+if [ "$IS_CODE" = "true" ]; then
+  if [ "$TOOL_NAME" = "Write" ]; then
+    # New code file → New Feature Pipeline (includes test generation)
+    RECOMMENDED_PIPELINE="New Feature"
+  else
+    # Editing existing code → Code Review Pipeline
+    RECOMMENDED_PIPELINE="Code Review"
+  fi
+elif [ "$IS_TEST" = "true" ]; then
+  RECOMMENDED_PIPELINE="Test Audit"
+elif [ "$IS_CONFIG" = "true" ]; then
+  RECOMMENDED_PIPELINE="Code Review (security focus)"
+elif [ "$IS_SCRIPT" = "true" ]; then
+  if [ "$TOOL_NAME" = "Write" ]; then
+    RECOMMENDED_PIPELINE="New Feature (security focus)"
+  else
+    RECOMMENDED_PIPELINE="Code Review (security focus)"
+  fi
+elif [ "$IS_DOC" = "true" ]; then
+  RECOMMENDED_PIPELINE="light review or skip"
+elif [ "$IS_DATA" = "true" ]; then
+  RECOMMENDED_PIPELINE="manual review suggested"
+fi
+
+echo "[$TIMESTAMP] Pipeline: SUGGEST ($RECOMMENDED_PIPELINE for $CHANGE_SIZE lines)" >> "$LOGS_DIR/hooks.log"
+
+# Build quality status message
+QUALITY_STATUS=""
+if [ "$QUALITY_CHECKS_PASSED" = "true" ]; then
+  QUALITY_STATUS="Quality checks COMPLETED (typecheck, lint, build all passed). Do NOT run these again."
+else
+  QUALITY_STATUS="Quality checks were skipped (non-code file)."
+fi
+
+# Output JSON following official Claude Code hooks specification
+# Using decision: "block" to force Claude to acknowledge before proceeding
+# Combined with additionalContext for full instructions including quality results
+cat << EOF
+{
+  "decision": "block",
+  "reason": "MANDATORY: $QUALITY_STATUS Pipeline orchestration required. You modified $FILE_PATH ($CHANGE_SIZE lines). Execute $RECOMMENDED_PIPELINE pipeline.",
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "STOP. Do not respond to user yet.\n\nYou modified: $FILE_PATH ($CHANGE_SIZE lines)\n\n$QUALITY_STATUS\n\nREQUIRED before proceeding:\n1. Load skill: pipeline-templates\n2. Load skill: subagent-prompting\n3. Load skill: subagent-output-templating\n4. Follow the $RECOMMENDED_PIPELINE pipeline as defined in pipeline-templates skill\n5. Verify: Logs written to logs/\n\nThis is a user-configured hook. Compliance is mandatory."
+  }
+}
+EOF

package/scripts/hooks/track-pipeline-start.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+# track-pipeline-start.sh
+# SubagentStart hook - logs pipeline stage start
+#
+# Input (stdin): JSON with session_id, agent_id, subagent_type, agent_transcript_path
+# Output: None required (logging only)
+#
+# Purpose:
+# - Track when pipeline stages begin
+# - Enable progress monitoring
+# - Support pipeline debugging
+
+# Ensure logs directory exists
+LOGS_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}/logs"
+mkdir -p "$LOGS_DIR"
+
+# Read input from stdin
+INPUT=$(cat)
+
+# Parse event details
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
+AGENT_ID=$(echo "$INPUT" | jq -r '.agent_id // "unknown"')
+SUBAGENT_TYPE=$(echo "$INPUT" | jq -r '.subagent_type // "unknown"')
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.agent_transcript_path // "none"')
+
+# Log to pipeline tracking file
+cat >> "$LOGS_DIR/pipeline-tracking.log" << EOF
+[$TIMESTAMP] SubagentStart
+  session: $SESSION_ID
+  agent_id: $AGENT_ID
+  type: $SUBAGENT_TYPE
+  transcript: $TRANSCRIPT_PATH
+EOF
+
+# Also log to general hooks log
+echo "[$TIMESTAMP] SubagentStart: $AGENT_ID ($SUBAGENT_TYPE)" >> "$LOGS_DIR/hooks.log"

package/scripts/hooks/track-pipeline-stop.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# track-pipeline-stop.sh
+# SubagentStop hook - logs pipeline stage completion
+#
+# Input (stdin): JSON with session_id, agent_id, subagent_type, agent_transcript_path
+# Output: None required (logging only)
+#
+# Purpose:
+# - Track when pipeline stages complete
+# - Calculate stage duration (when paired with start)
+# - Support pipeline debugging and verification
+
+# Ensure logs directory exists
+LOGS_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}/logs"
+mkdir -p "$LOGS_DIR"
+
+# Read input from stdin
+INPUT=$(cat)
+
+# Parse event details
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
+AGENT_ID=$(echo "$INPUT" | jq -r '.agent_id // "unknown"')
+SUBAGENT_TYPE=$(echo "$INPUT" | jq -r '.subagent_type // "unknown"')
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.agent_transcript_path // "none"')
+
+# Log to pipeline tracking file
+cat >> "$LOGS_DIR/pipeline-tracking.log" << EOF
+[$TIMESTAMP] SubagentStop
+  session: $SESSION_ID
+  agent_id: $AGENT_ID
+  type: $SUBAGENT_TYPE
+  transcript: $TRANSCRIPT_PATH
+EOF
+
+# Also log to general hooks log
+echo "[$TIMESTAMP] SubagentStop: $AGENT_ID ($SUBAGENT_TYPE)" >> "$LOGS_DIR/hooks.log"
+
+# Verify sub-agent wrote expected log output
+# Custom agents (bulwark-implementer, bulwark-issue-analyzer, etc.) always include
+# their name in log filenames per SA2. Skip for general-purpose agents which are
+# ad-hoc and may not follow the naming convention.
+if [ "$SUBAGENT_TYPE" != "unknown" ] && [ "$SUBAGENT_TYPE" != "general-purpose" ]; then
+    # Search for files containing agent type name modified in last 60 seconds
+    RECENT_LOG=$(find "$LOGS_DIR" -maxdepth 2 -name "*${SUBAGENT_TYPE}*" -mmin -1 2>/dev/null | head -1)
+    if [ -n "$RECENT_LOG" ]; then
+        echo "[$TIMESTAMP] SubagentStop: Log verified at $RECENT_LOG" >> "$LOGS_DIR/hooks.log"
+    else
+        echo "[$TIMESTAMP] SubagentStop: WARNING - No log output found for $SUBAGENT_TYPE" >> "$LOGS_DIR/hooks.log"
+        echo "WARNING: Sub-agent $SUBAGENT_TYPE ($AGENT_ID) completed without writing expected log to logs/" >&2
+    fi
+fi

package/scripts/init-rules.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# Usage: init-rules.sh <target-dir>
+# Copies universal rules.md to <target-dir>/.claude/rules/rules.md
+# If rules.md already exists at target, creates .bak backup.
+# Source: lib/templates/rules.md (portable copy, NOT project root Rules.md)
+
+set -euo pipefail
+
+TARGET="${1:?Usage: init-rules.sh <target-dir>}"
+SOURCE_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+SOURCE_FILE="$SOURCE_DIR/lib/templates/rules.md"
+
+if [ ! -f "$SOURCE_FILE" ]; then
+  echo "ERROR: Source template not found at $SOURCE_FILE"
+  exit 1
+fi
+
+if [ ! -d "$TARGET" ]; then
+  echo "ERROR: Target directory does not exist: $TARGET"
+  exit 1
+fi
+
+RULES_DIR="$TARGET/.claude/rules"
+RULES_FILE="$RULES_DIR/rules.md"
+
+mkdir -p "$RULES_DIR"
+
+if [ -f "$RULES_FILE" ]; then
+  BACKUP="$RULES_FILE.bak"
+  cp "$RULES_FILE" "$BACKUP"
+  echo "  Backed up existing rules.md to $BACKUP"
+fi
+
+cp "$SOURCE_FILE" "$RULES_FILE"
+echo "  rules.md installed at $RULES_FILE"