@qball-inc/the-bulwark 1.0.1 → 1.1.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "the-bulwark",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Full-lifecycle SDLC guardrailing framework for Claude Code — from product ideation and planning through implementation, code review, and test validation. Enterprise-grade skills and agents for AI-human peer collaboration.",
   "author": {
     "name": "Ashay Kubal",
@@ -38,6 +38,5 @@
     "test-coverage",
     "statusline",
     "agent-teams"
-  ],
-  "hooks": "./hooks/hooks.json"
+  ]
 }

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashay Kubal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -15,7 +15,8 @@
   <a href="#how-it-works">How it works</a> &middot;
   <a href="#hooks">Hooks</a> &middot;
   <a href="#skill-registry">Skills</a> &middot;
-  <a href="#agent-registry">Agents</a>
+  <a href="#agent-registry">Agents</a> &middot;
+  <a href="#planned-enhancements">Roadmap</a>
 </p>
 
 <p align="center">
@@ -92,6 +93,8 @@ After installing, restart your Claude Code session and run the init skill:
 
 This walks you through a guided setup: Rules.md injection, CLAUDE.md configuration, and optional tooling (LSP, Justfile scaffolding, statusline). It auto-detects brownfield projects and adjusts accordingly.
 
+> Having trouble installing? See [FAQ and troubleshooting](#faq-and-troubleshooting). If your issue isn't covered, please [open an issue](https://github.com/QBall-Inc/the-bulwark/issues).
+
 ## Prerequisites
 
 | Requirement | Details |
@@ -297,6 +300,23 @@ Agents are single-purpose sub-agents spawned by skills via the Task tool. You do
 
 ## FAQ and troubleshooting
 
+### Plugin clone fails with "Permission denied (publickey)"
+
+If you see this error when installing from the marketplace:
+
+```
+git@github.com: Permission denied (publickey).
+fatal: Could not read from remote repository.
+```
+
+Your git is defaulting to SSH for GitHub, but you don't have SSH keys configured. Fix by telling git to use HTTPS:
+
+```bash
+git config --global url."https://github.com/".insteadOf "git@github.com:"
+```
+
+Then retry the install. This applies globally and redirects all GitHub SSH URLs to HTTPS.
+
 ### Hooks aren't firing after install
 
 Restart your Claude Code session. Hooks only load at session start. If they still don't fire, check that the plugin is installed:
@@ -357,6 +377,26 @@ You can't disable individual plugin hooks without modifying `hooks/hooks.json` i
 
 ---
 
+## Planned enhancements
+
+These are on the roadmap. No timeline commitments, but they represent the direction The Bulwark is heading.
+
+**Evaluation framework.** Skills and agents are the new code layer in agentic development. They need the same rigor as code: versioned, tested, measured. We're building two new skills — `create-eval` and `run-eval` — that generate and execute evaluations for any Claude Code asset. Define test prompts, expected outputs, and grading criteria. Run them across skill versions to catch regressions. Measure conversational invocation success, checklist compliance, and output quality with structured grading reports.
+
+**Asset baselines.** Once the eval skills exist, we'll baseline all 28 skills and 15 agents with versioned evaluations. Every asset gets a `version` field in its frontmatter and a set of evals that serve as regression references. Future changes get measured against these baselines automatically.
+
+**Enterprise traceability.** Enhanced logging with version stamps (skill version, model, rules hash) in every sub-agent log header. Run manifests that tie together all artifacts from a pipeline execution into a single auditable record. Decision lineage: trace any output back to which model, skill version, and rules produced it.
+
+**Security pattern updates.** A helper skill that pulls the latest vulnerability patterns and edge cases into the test-audit pipeline. Keeps your security coverage current without manual curation.
+
+**Framework-specific Justfiles.** Auto-detect your project's framework (Next.js, Django, FastAPI, Actix, etc.) and generate tailored `just` recipes with the right build, test, and lint commands out of the box.
+
+**Agent memory.** Persistent memory for sub-agents across invocations. Agents remember patterns from previous runs — common failure modes, project-specific conventions, recurring issues — and apply that context automatically.
+
+**Smarter pipeline routing.** Better orchestration for review-then-fix workflows. When a code review finds issues, automatically route to fix validation without manual intervention. Tighter feedback loops between review, fix, and retest stages.
+
+---
+
 ## License
 
 [MIT](LICENSE)

package/hooks/hooks.json

@@ -35,6 +35,17 @@
         ]
       }
     ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/suggest-pipeline-stop.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
     "SessionStart": [
       {
         "hooks": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qball-inc/the-bulwark",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Full-lifecycle SDLC guardrailing framework for Claude Code — from product ideation and planning through implementation, code review, and test validation. Enterprise-grade skills and agents for AI-human peer collaboration.",
   "license": "MIT",
   "author": "Ashay Kubal <https://ashaykubal.com>",

package/scripts/hooks/enforce-quality.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# enforce-quality.sh - Quality gate + pipeline suggestion (chained execution)
+# enforce-quality.sh - Quality gate + changed-files accumulator
 #
 # Called by PostToolUse hooks on Write|Edit operations.
 #
@@ -7,12 +7,16 @@
 #   - Runs just typecheck, lint, build
 #   - Exit 2 on failure (blocks tool call)
 #
-# Phase 2: Pipeline suggestion (all files)
-#   - Chains to suggest-pipeline.sh
-#   - Passes through stdin JSON for change analysis
+# Phase 2: Accumulator write (code + script files only)
+#   - Appends file path to tmp/bulwark-changed-files.json
+#   - Excludes docs, config, infra paths via extension + prefix filter
+#   - Dedup on path
+#   - Stop hook (suggest-pipeline-stop.sh) reads accumulator and emits
+#     exactly ONE pipeline-suggestion block per turn — replacing the legacy
+#     per-edit decision:block anti-pattern (hook storm / silent crash).
 #
 # Exit codes:
-#   0 = All checks passed, pipeline suggestion complete
+#   0 = All checks passed, accumulator updated
 #   2 = Quality gate failed (block)
 #
 # Usage: Called by hooks, not directly by users
@@ -22,14 +26,11 @@ set -euo pipefail
 # Configuration
 MAX_OUTPUT_LINES=100
 
-# Color codes (if terminal supports)
-RED='\033[0;31m'
-GREEN='\033[0;32m'
+# Color codes (if terminal supports) — used for warning banners only
 YELLOW='\033[0;33m'
 NC='\033[0m' # No Color
 
 # Get directories
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 LOGS_DIR="${PROJECT_DIR}/logs"
 HOOKS_LOG="${LOGS_DIR}/hooks.log"
@@ -48,10 +49,18 @@ echo "[${TIMESTAMP}] PostToolUse: enforce-quality.sh triggered for ${FILE_PATH_F
 # Extract file path from input
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
 
-# Skip infrastructure directories (no quality checks or pipeline suggestions)
+# Normalize absolute path to repo-relative (if under PROJECT_DIR)
+REL_PATH="$FILE_PATH"
+if [ -n "$FILE_PATH" ] && [ "${PROJECT_DIR}" != "." ] && [[ "$REL_PATH" == "$PROJECT_DIR/"* ]]; then
+    REL_PATH="${REL_PATH#"$PROJECT_DIR/"}"
+fi
+
+# Skip infrastructure directories (no quality checks or pipeline suggestions).
+# Matches against REPO-RELATIVE path — absolute-path glob matching was a bug:
+# any project under a path containing /tmp/, /logs/, etc. was ignored entirely.
 # DEF-005: Prevents infinite loops when writing to logs/
-case "$FILE_PATH" in
-  */logs/*|logs/*|*/tmp/*|tmp/*|*/.claude/*|.claude/*|*/node_modules/*|node_modules/*)
+case "$REL_PATH" in
+  logs/*|tmp/*|.claude/*|node_modules/*|dist/*|build/*|.git/*)
     exit 0
     ;;
 esac
@@ -145,22 +154,62 @@ if is_code_file "$FILE_PATH"; then
                 }
             fi
 
-            # Export quality results for suggest-pipeline.sh
-            export QUALITY_CHECKS_PASSED="true"
         fi
     fi
 fi
 
 # ============================================================
-# PHASE 2: Pipeline Suggestion (all file types)
+# PHASE 2: Accumulator Write (code + script files only)
 # ============================================================
+#
+# Legacy Phase 2 chained to suggest-pipeline.sh, which emitted one
+# decision:block per edit — cascading into N interrupts on multi-edit turns.
+# Replaced by: append qualifying file path to accumulator; Stop hook
+# (suggest-pipeline-stop.sh) emits exactly one block at turn end.
+
+# Skip accumulator write if no file path (defensive)
+if [ -z "$FILE_PATH" ]; then
+    exit 0
+fi
+
+# --- Exclusion filter: extensions ---
+# Docs, config, data files do not warrant pipeline orchestration.
+# Prefix exclusions (logs/, tmp/, .claude/, node_modules/, dist/, build/, .git/)
+# already exited at the top-of-file skip. REL_PATH is also pre-computed there.
+FILENAME=$(basename "$FILE_PATH")
+EXTENSION="${FILENAME##*.}"
+EXTENSION_LOWER=$(echo "$EXTENSION" | tr '[:upper:]' '[:lower:]')
+
+case "$EXTENSION_LOWER" in
+    md|markdown|json|jsonc|yaml|yml|xml|csv|tsv|txt|docx|xlsx|pdf|html|htm)
+        exit 0
+        ;;
+esac
+
+# --- Accumulator: ensure directory, validate, append with dedup ---
+ACCUMULATOR_DIR="${PROJECT_DIR}/tmp"
+ACCUMULATOR="${ACCUMULATOR_DIR}/bulwark-changed-files.json"
+mkdir -p "$ACCUMULATOR_DIR"
 
-SUGGEST_SCRIPT="${SCRIPT_DIR}/suggest-pipeline.sh"
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"')
+ACC_TIMESTAMP=$(date -Iseconds)
+
+# Recover from corrupt accumulator
+if [ -f "$ACCUMULATOR" ] && ! jq -e '.' "$ACCUMULATOR" >/dev/null 2>&1; then
+    rm -f "$ACCUMULATOR"
+fi
 
-if [ -x "$SUGGEST_SCRIPT" ]; then
-    # Pass through the original input to suggest-pipeline.sh
-    echo "$INPUT" | "$SUGGEST_SCRIPT"
+if [ ! -f "$ACCUMULATOR" ]; then
+    jq -n --arg p "$REL_PATH" --arg t "$TOOL_NAME" --arg ts "$ACC_TIMESTAMP" \
+        '{version: "1.0", files: [{path: $p, tool: $t, time: $ts}]}' > "$ACCUMULATOR"
 else
-    # suggest-pipeline.sh not found - not an error, just skip
-    exit 0
+    # Dedup: append only if path not already present
+    EXISTING=$(jq -r --arg p "$REL_PATH" '.files[] | select(.path == $p) | .path' "$ACCUMULATOR" 2>/dev/null || echo "")
+    if [ -z "$EXISTING" ]; then
+        jq --arg p "$REL_PATH" --arg t "$TOOL_NAME" --arg ts "$ACC_TIMESTAMP" \
+            '.files += [{path: $p, tool: $t, time: $ts}]' "$ACCUMULATOR" > "${ACCUMULATOR}.tmp" \
+            && mv "${ACCUMULATOR}.tmp" "$ACCUMULATOR"
+    fi
 fi
+
+exit 0

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

@@ -0,0 +1,118 @@
+#!/bin/bash
+# suggest-pipeline-stop.sh - Stop-hook handler for consolidated pipeline suggestions
+#
+# Fires at the end of every Claude turn. Reads the changed-files accumulator
+# written by enforce-quality.sh and emits exactly one `decision: block`
+# pipeline suggestion per turn, citing all qualifying files.
+#
+# Replaces the PostToolUse-per-edit `decision: block` anti-pattern from
+# legacy suggest-pipeline.sh, which cascaded N interruptions on multi-edit
+# turns (the "hook storm" / "silent crash").
+#
+# Input (stdin): Stop hook JSON per Anthropic spec:
+#   - stop_hook_active (bool)       recursion guard; true if already firing
+#   - stop_reason (string)          end_turn | user_interrupt | max_tokens
+#   - session_id (string)           current session id
+#   - transcript_path (string)      path to turn transcript
+#   - cwd (string)                  working directory
+#   - permission_mode (string)      current permission mode
+#   - hook_event_name (string)      always "Stop" here
+#
+# Output (stdout):
+#   - {"decision": "block", "reason": ...} when accumulator is non-empty;
+#     prevents Claude from ending the turn until the suggested pipeline runs.
+#   - {} otherwise (silent pass).
+#
+# NOTE: Stop hooks do NOT support `hookSpecificOutput` / `additionalContext`
+# per the Claude Code schema (https://code.claude.com/docs/en/hooks). Valid
+# top-level fields for Stop hooks: decision, reason, continue, stopReason,
+# suppressOutput, systemMessage. All instruction content must live in `reason`.
+#
+# Accumulator contract: see scripts/hooks/enforce-quality.sh (writer).
+# Path: ${CLAUDE_PROJECT_DIR:-$(pwd)}/tmp/bulwark-changed-files.json
+# Schema: {"version": "1.0", "files": [{"path", "tool", "time"}]}
+
+set -euo pipefail
+
+# Read stdin once
+INPUT=$(cat)
+
+# Resolve project directory
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+LOGS_DIR="${PROJECT_DIR}/logs"
+ACCUMULATOR="${PROJECT_DIR}/tmp/bulwark-changed-files.json"
+
+mkdir -p "$LOGS_DIR"
+HOOKS_LOG="${LOGS_DIR}/hooks.log"
+TIMESTAMP=$(date -Iseconds)
+
+# --- Recursion guard ---
+# If a prior Stop hook already blocked and Claude is now responding to that
+# block, stop_hook_active is true. Short-circuit to prevent infinite loops.
+STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
+if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
+  echo "[${TIMESTAMP}] Stop: recursion guard active, exiting silently" >> "$HOOKS_LOG"
+  echo '{}'
+  exit 0
+fi
+
+# --- Accumulator absent or empty → silent pass ---
+if [ ! -f "$ACCUMULATOR" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# Validate JSON; corrupt → drop and exit silently
+if ! jq -e '.' "$ACCUMULATOR" >/dev/null 2>&1; then
+  echo "[${TIMESTAMP}] Stop: corrupt accumulator, resetting" >> "$HOOKS_LOG"
+  rm -f "$ACCUMULATOR"
+  echo '{}'
+  exit 0
+fi
+
+FILE_COUNT=$(jq -r '.files | length' "$ACCUMULATOR" 2>/dev/null || echo "0")
+if [ "$FILE_COUNT" = "0" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# --- Categorize files for targeted pipeline suggestion ---
+CODE_FILES=$(jq -r '[.files[] | select(.path | test("\\.(ts|tsx|js|jsx|py|go|rs|java|cpp|c|rb|php|swift|kt)$"; "i"))] | length' "$ACCUMULATOR")
+TEST_FILES=$(jq -r '[.files[] | select(.path | test("(test|spec|_test)\\.(ts|tsx|js|jsx|py|go|rs|java|cpp|rb)$"; "i"))] | length' "$ACCUMULATOR")
+SCRIPT_FILES=$(jq -r '[.files[] | select(.path | test("\\.(sh|bash|zsh|fish|ps1)$"; "i"))] | length' "$ACCUMULATOR")
+
+# Choose dominant pipeline
+RECOMMENDED_PIPELINE="Code Review"
+if [ "$TEST_FILES" -gt 0 ] && [ "$TEST_FILES" -ge "$CODE_FILES" ]; then
+  RECOMMENDED_PIPELINE="Test Audit"
+elif [ "$SCRIPT_FILES" -gt 0 ] && [ "$SCRIPT_FILES" -ge "$CODE_FILES" ]; then
+  RECOMMENDED_PIPELINE="Code Review (security focus)"
+fi
+
+# --- Build file list for reason field (sanitized for newline injection) ---
+FILE_LIST=$(jq -r '.files[] | "- " + .path + " (" + .tool + ")"' "$ACCUMULATOR" | tr -d '\r')
+
+echo "[${TIMESTAMP}] Stop: emitting block for ${FILE_COUNT} files, pipeline=${RECOMMENDED_PIPELINE}" >> "$HOOKS_LOG"
+
+# --- Emit blocking decision FIRST ---
+# Under `set -e`, if the accumulator reset fails (disk full, permission error),
+# emitting after the reset would silently drop the block. Emit first so the
+# user always gets the pipeline suggestion; reset is best-effort afterward.
+# Using jq to build the JSON safely (FILE_LIST may contain shell metachars).
+#
+# All instruction content goes into `reason` — Stop hooks do not support
+# `hookSpecificOutput.additionalContext` per CC schema.
+REASON=$(printf 'Pipeline orchestration required. You modified %d file(s) this turn:\n%s\n\nSTOP. Do not respond to user yet.\n\nREQUIRED before proceeding:\n1. Load skill: pipeline-templates\n2. Load skill: subagent-prompting\n3. Load skill: subagent-output-templating\n4. Follow the %s pipeline as defined in pipeline-templates skill\n5. Verify: Logs written to logs/\n\nThis is a user-configured hook. Compliance is mandatory.' "$FILE_COUNT" "$FILE_LIST" "$RECOMMENDED_PIPELINE")
+
+jq -n \
+  --arg reason "$REASON" \
+  '{
+    "decision": "block",
+    "reason": $reason
+  }'
+
+# --- Reset accumulator (best-effort checkpoint) ---
+# || true: if reset fails, at worst the same files re-surface next turn and
+# the recursion guard (stop_hook_active) still prevents an immediate loop.
+jq -n '{version: "1.0", files: []}' > "$ACCUMULATOR" 2>>"$HOOKS_LOG" || \
+    echo "[${TIMESTAMP}] Stop: accumulator reset FAILED — may re-surface next turn" >> "$HOOKS_LOG"

package/scripts/hooks/suggest-pipeline.sh

@@ -1,4 +1,16 @@
 #!/bin/bash
+# DEPRECATED as of P10.1 (Session 101, 2026-04-20)
+# ================================================================
+# This script emitted `decision: block` on EVERY PostToolUse, which
+# cascaded into N interrupts on multi-edit turns (the "hook storm" /
+# "silent crash"). Replaced by:
+#   - scripts/hooks/enforce-quality.sh (accumulator write, no block)
+#   - scripts/hooks/suggest-pipeline-stop.sh (one block per turn at Stop)
+#
+# No live caller should invoke this script. Retained one release cycle
+# for rollback safety; scheduled for removal after P10 completion.
+# ================================================================
+#
 # suggest-pipeline.sh
 # PostToolUse hook for Write|Edit - suggests pipeline orchestration after code changes
 #

package/scripts/init.sh

@@ -97,6 +97,14 @@ if [ ! -f "$CLAUDE_TEMPLATE" ]; then
   exit 1
 fi
 
+# --- Ensure `just` is installed (hard dependency for scaffold-produced Justfiles) ---
+
+# shellcheck source=./install-just.sh
+source "$SCRIPT_DIR/install-just.sh"
+install_just
+
+echo ""
+
 # --- Install CLAUDE.md ---
 
 if [ -f "$CLAUDE_TARGET" ]; then