@qball-inc/the-bulwark 1.0.0

package/skills/create-subagent/references/template-single-agent.md

@@ -0,0 +1,192 @@
+# Template: Single-Purpose Agent
+
+Use this template when the agent performs a single focused task without sub-agent orchestration. Typical for reviewers, analyzers, classifiers, and specialized workers.
+
+---
+
+## File Output
+
+```
+.claude/agents/{agent-name}.md
+```
+
+Single file — no supporting directories needed.
+
+## Generated Agent Structure
+
+```markdown
+---
+name: {agent-name}
+description: {single-line, role-based, trigger-specific}
+model: {haiku|sonnet|opus}
+tools:
+  - {tool-1}
+  - {tool-N}
+skills:
+  - subagent-output-templating
+---
+
+# {Agent Title}
+
+You are a {role description}. Your expertise covers {domain areas}.
+
+---
+
+## Pre-Flight Gate
+
+**MANDATORY: Read this section FIRST. These instructions are BINDING, not advisory.**
+
+Before doing ANY work, confirm you understand these REQUIRED obligations:
+
+1. **REQUIRED**: {obligation 1}
+2. **REQUIRED**: {obligation 2}
+3. **REQUIRED**: Write output to the exact paths specified in Output section
+
+Failure to follow these obligations produces non-compliant output.
+
+---
+
+## Your Mission
+
+**DO**:
+- {concrete action 1}
+- {concrete action 2}
+- {concrete action 3}
+- Follow existing patterns and conventions in the target codebase
+
+**DO NOT**:
+- {specific prohibition 1}
+- {specific prohibition 2}
+- Write files outside the scope of the task
+
+---
+
+## Invocation
+
+This agent is invoked via the **Task tool**:
+
+| Method | How to Use |
+|--------|-----------|
+| **Direct** | `Task(subagent_type="{agent-name}", prompt="...")` |
+| **User request** | Ask Claude to "run the {agent-name}" |
+
+**Input handling**:
+1. Read task details from the prompt
+2. Parse input for required fields
+3. Validate inputs exist before proceeding
+
+---
+
+## Protocol
+
+### Step 1: Parse Input
+
+{What to extract from the invoking prompt.}
+
+### Step 2: Read Context
+
+{What files/data to read before doing work.}
+
+### Step 3: Execute
+
+{Core work the agent performs. Describe behavioral approach, not mechanical steps.}
+
+### Step 4: Write Output
+
+1. Write main report to `$PROJECT_DIR/logs/{agent-name}-{timestamp}.{ext}`
+2. Write diagnostics to `$PROJECT_DIR/logs/diagnostics/{agent-name}-{timestamp}.yaml`
+
+### Step 5: Return Summary
+
+Return a summary to the invoker (100-300 tokens). Include:
+- What was done
+- Key findings or results
+- Report path
+
+---
+
+## Tool Usage Constraints
+
+### {Tool 1}
+- **Allowed**: {specific allowed uses}
+- **Forbidden**: {specific forbidden uses}
+
+---
+
+## Output
+
+### Main Report
+
+**Location**: `$PROJECT_DIR/logs/{agent-name}-{timestamp}.{ext}`
+
+{Report format specification.}
+
+### Diagnostics
+
+**Location**: `$PROJECT_DIR/logs/diagnostics/{agent-name}-{timestamp}.yaml`
+
+\`\`\`yaml
+diagnostic:
+  agent: {agent-name}
+  timestamp: "{ISO-8601}"
+
+  task:
+    description: "{what was requested}"
+    input: "{input provided}"
+
+  execution:
+    steps_completed: 0
+    findings: 0
+    errors: 0
+
+  output:
+    report_path: "$PROJECT_DIR/logs/{agent-name}-{timestamp}.{ext}"
+    verdict: "{pass/fail/complete/partial}"
+\`\`\`
+
+### Summary (Return to Invoker)
+
+**Token budget**: 100-300 tokens
+
+---
+
+## Permissions Setup
+
+This agent requires the following configuration:
+
+### Tool Permissions
+
+Add to `.claude/settings.json` or `.claude/settings.local.json`:
+
+\`\`\`json
+{
+  "permissions": {
+    "allow": [
+      "{tool-1}",
+      "{tool-N}"
+    ]
+  }
+}
+\`\`\`
+
+---
+
+## Completion Checklist
+
+- [ ] All steps executed
+- [ ] Main report written to `$PROJECT_DIR/logs/`
+- [ ] Diagnostic YAML written
+- [ ] Summary returned to invoker
+```
+
+## Guidance for Generator
+
+- Write in system-prompt register (WHO the agent IS, not WHAT to do)
+- Open with identity statement: "You are a..."
+- Include Pre-Flight Gate with MUST/MUST NOT (binding language, DEF-P4-005)
+- Include DO/DO NOT mission section
+- Include tool usage constraints for every tool listed in frontmatter
+- Include Permissions Setup section (tool permissions unsolved per #10093)
+- Include diagnostic output section with YAML schema
+- Single-purpose agents are typically 150-250 lines
+- Default model: Sonnet (unless task needs Haiku speed or Opus depth)

package/skills/fix-bug/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: fix-bug
+description: Run the Fix Validation pipeline to investigate, fix, and validate a bug. Ensures deterministic pipeline execution with IssueAnalyzer, FixWriter, TestWriter (conditional), TestAudit (conditional), and FixValidator stages.
+user-invocable: true
+---
+
+# Fix Bug Pipeline
+
+This skill triggers the **Fix Validation pipeline** to systematically investigate, fix, and validate a bug.
+
+## When to Use This Skill
+
+**Load this skill when the user request matches ANY of these patterns:**
+
+| Trigger Pattern | Example User Request |
+|-----------------|---------------------|
+| Bug fix requests | "Fix this bug", "Something is broken in X" |
+| Error investigation | "Users report errors in X", "This feature isn't working" |
+| Regression fixes | "This used to work", "Breaking after recent changes" |
+| Production issues | "Login fails for new accounts", "API returns 500" |
+| Flaky behavior | "Tests pass sometimes", "Intermittent failures" |
+
+**DO NOT use this skill for:**
+
+| Anti-Pattern | Use Instead |
+|--------------|-------------|
+| Ad-hoc fixes without investigation | Direct fix (skip pipeline) |
+| Simple typo corrections | Direct edit |
+| Refactoring without reported issues | Code Review pipeline |
+| Adding new features | New Feature pipeline |
+| Performance optimization | Research & Planning pipeline |
+
+## Why This Skill Exists
+
+Without this skill, conversational prompts like "please investigate and fix this bug" may cause Claude to skip pipeline stages and fix directly. This skill ensures **deterministic execution** of all Fix Validation pipeline stages.
+
+## Usage
+
+```
+/fix-bug <path> [description]
+```
+
+**Arguments**:
+- `$1` (required): Path to code with the bug
+- `$2` and beyond (optional): Description of the issue - recommended for better analysis
+
+**Examples**:
+```
+/fix-bug src/auth/login.ts "Users report login fails for new accounts"
+/fix-bug tests/fixtures/fix-validator/simple-fix/ "Cannot read property displayName of undefined"
+/fix-bug src/api/routes.ts
+```
+
+## Pipeline Stages
+
+When invoked, follow the Fix Validation pipeline exactly:
+
+```fsharp
+IssueAnalyzer (bulwark-issue-analyzer)          // Sonnet - root cause analysis
+|> FixWriter (bulwark-implementer)              // Opus - implement fix
+|> (if !tests_cover_scenario                    // Conditional: only if tests don't already exist
+    then TestWriter |> TestAudit                // Opus writes, then audit for T1-T4
+    else Skip)
+|> FixValidator (bulwark-fix-validator)          // Sonnet - validate against debug report
+|> CodeReviewer (general-purpose)               // Sonnet - review fix
+|> (if !approved
+    then IssueAnalyzer                          // Loop back
+    else Done)
+|> LOOP(max=3)                                  // Max 3 iterations
+```
+
+## Execution Instructions
+
+### Stage 1: IssueAnalyzer
+
+**MUST** spawn `bulwark-issue-analyzer` agent via Task tool:
+
+```
+Task(
+  subagent_type="bulwark-issue-analyzer",
+  model="sonnet",
+  prompt="GOAL: Analyze the bug and produce a debug report..."
+)
+```
+
+**Input**: Path from `$1`, description from `$2` onward
+
+**Output**: Debug report at `logs/debug-reports/{issue-id}-{timestamp}.yaml`
+
+**Do NOT** skip this stage. The debug report is required for subsequent stages.
+
+### Stage 2: FixWriter
+
+**MUST** spawn `bulwark-implementer` agent via Task tool:
+
+```
+Task(
+  subagent_type="bulwark-implementer",
+  prompt="GOAL: Fix the identified issue based on the debug report.
+  CONSTRAINTS: Only fix the identified issue. Write tests for the fix. Max 3 quality gate retries.
+  CONTEXT:
+    mode: fix
+    debug_report_path: logs/debug-reports/{issue-id}-{timestamp}.yaml
+    root_cause: {from Stage 1}
+    affected_files: {from Stage 1}
+    fix_approach: {from Stage 1}
+  OUTPUT: Implementation report at logs/implementer-{id}-{timestamp}.yaml"
+)
+```
+
+**Input**: Debug report from Stage 1
+
+**Output**: Implementation report at `logs/implementer-{id}-{timestamp}.yaml`
+
+**SA6 Note**: The implementer returns pipeline suggestions with MANDATORY language in its summary. Evaluate each suggestion per SA6.
+
+**Do NOT** implement the fix yourself. The implementer agent handles quality gates and structured output.
+
+### Stage 3: TestWriter (Conditional)
+
+**Condition**: Check debug report's `validation_plan.recommendation.new_tests_needed`
+
+**If tests needed**:
+1. Write tests that verify the fix
+2. Cover the specific bug scenario
+3. Follow T1-T4 rules (no mocking system under test)
+
+**If tests exist**: Skip to Stage 3b or Stage 4
+
+### Stage 3b: TestAudit (Conditional)
+
+**Condition**: Run if **any** test files were created or modified in Stage 2 (FixWriter) OR Stage 3 (TestWriter). This ensures implementer-written tests receive T1-T4 audit even when TestWriter is skipped.
+
+**Action**: Run mock-detection on new/modified tests to verify T1-T4 compliance
+
+**If T1 violation**: Return to TestWriter (or FixWriter if TestWriter was skipped), request rewrite
+
+**If T2-T4 violations**: Log warning, proceed
+
+### Stage 4: FixValidator
+
+**MUST** spawn `bulwark-fix-validator` agent via Task tool:
+
+```
+Task(
+  subagent_type="bulwark-fix-validator",
+  model="sonnet",
+  prompt="GOAL: Validate the fix against the debug report...
+
+  CONTEXT:
+  Debug Report: logs/debug-reports/{issue-id}-{timestamp}.yaml
+  Fix Applied: {description of changes}
+  Tests Added: {if any}
+  ..."
+)
+```
+
+**Input**: Debug report path, fix details, test details
+
+**Output**: Validation report at `logs/validations/fix-validation-{issue-id}-{timestamp}.yaml`
+
+### Stage 5: CodeReviewer
+
+**MUST** spawn `general-purpose` agent via Task tool:
+
+```
+Task(
+  subagent_type="general-purpose",
+  model="sonnet",
+  prompt="GOAL: Review the fix for correctness, completeness, and safety.
+  CONSTRAINTS: Do NOT modify any files. Review only.
+  CONTEXT:
+    debug_report: logs/debug-reports/{issue-id}-{timestamp}.yaml
+    fix_applied: {description of changes from Stage 2}
+    tests_added: {from Stage 3, if any}
+    validation_results: {from Stage 4}
+  OUTPUT: Approval decision (approved: true/false) with concerns and recommendations."
+)
+```
+
+**Approval Criteria**:
+- Fix addresses root cause from debug report
+- Tests verify the specific bug scenario
+- No new issues introduced
+- Validation confidence is acceptable (high or medium with justification)
+
+### Loop Handling
+
+If rejected and iterations < 3:
+- Return to Stage 1 with feedback
+- Include previous validation results
+
+If rejected and iterations >= 3:
+- Escalate to user
+- Summarize all attempts
+
+## Progress Reporting
+
+After each stage, report progress to user:
+
+```
+Stage 1 (IssueAnalyzer): Complete
+  - Debug report: logs/debug-reports/AUTH-001-20260120.yaml
+  - Root cause: {summary}
+  - Complexity: {low|medium|high}
+
+Stage 2 (FixWriter): Complete
+  - Files modified: {list}
+  - Fix: {brief description}
+
+Stage 3 (TestWriter): {Complete|Skipped}
+  - Tests added: {count or "existing tests sufficient"}
+
+Stage 4 (FixValidator): Complete
+  - Confidence: {HIGH|MEDIUM|LOW}
+  - Recommendation: {proceed|revise}
+
+Stage 5 (CodeReviewer): Complete
+  - Decision: {Approved|Rejected}
+```
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| IssueAnalyzer fails to identify root cause | Report to user, ask for more context |
+| Tests cannot be executed | FixValidator uses manual validation strategy |
+| FixValidator confidence is LOW | Escalate to user with details |
+| Max iterations reached | Summarize attempts, ask user for guidance |
+
+## Related Resources
+
+| Resource | Location |
+|----------|----------|
+| Pipeline definition | `pipeline-templates/references/fix-validation.md` |
+| IssueAnalyzer agent | `agents/bulwark-issue-analyzer.md` |
+| Implementer agent | `agents/bulwark-implementer.md` |
+| FixValidator agent | `agents/bulwark-fix-validator.md` |
+| Issue debugging skill | `issue-debugging/SKILL.md` |
+
+**Note**: Paths are relative to your skills/agents directory (either `skills/` or `.claude/skills/`).

package/skills/governance-protocol/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: governance-protocol
+description: Session governance protocol injected at startup via SessionStart hook
+user-invocable: false
+---
+
+**DISPLAY TO USER**: When you receive this protocol, immediately output the following banner exactly as shown:
+
+```
+═══════════════════════════════════════════════════════════════
+  BULWARK GOVERNANCE PROTOCOL - ACTIVATED
+  Quality enforcement enabled for this session
+═══════════════════════════════════════════════════════════════
+```
+
+Then proceed with the user's request.
+
+---
+
+## MANDATORY: Rules.md is Binding
+
+**YOU MUST READ AND FOLLOW `Rules.md` THROUGHOUT THIS SESSION.**
+
+This is not optional. This is not advisory. This is a binding, mandatory, non-negotiable contract.
+
+`Rules.md` contains immutable rules including:
+
+### SC1-SC3: Skill Compliance Rules (CRITICAL)
+
+When a skill is loaded:
+- **ALL instructions within the skill are BINDING**, not advisory
+- **You MUST spawn sub-agents when the skill specifies sub-agent spawning**
+- **You MUST NOT perform the sub-agent's work yourself**
+- **You MUST NOT substitute your judgment for skill instructions**
+- **You MUST NOT skip steps because they seem unnecessary**
+
+If you find yourself thinking "I can analyze this directly and give a faster answer" - **STOP**. That thought pattern violates SC1-SC2. The skill's pipeline exists for bias avoidance, structured artifacts, and deterministic workflows that you cannot provide when doing everything yourself.
+
+### Violation Consequences
+
+Ignoring skill instructions:
+- Defeats the purpose of the Bulwark quality enforcement system
+- Produces inconsistent, non-reproducible outputs
+- Bypasses bias separation that sub-agent pipelines enforce
+- Breaks the observability chain required for multi-agent workflows
+
+---
+
+## Bulwark Governance Protocol
+
+This session is governed by The Bulwark quality enforcement system.
+
+### How This Works
+
+This skill is automatically injected into Claude's context at session start via the SessionStart hook configured in `hooks/hooks.json`. It does not need to be manually invoked. The `inject-protocol.sh` script reads this file and outputs its content to Claude's context.
+
+### Quality Gates (Automatic)
+
+PostToolUse hooks run after every Write/Edit operation on code files:
+
+1. **Typecheck** - Code must pass type checking (`just typecheck`)
+2. **Lint** - Code must pass linting (`just lint`)
+3. **Build** - Code must compile/build (`just build`)
+
+Failures **BLOCK** the operation. You will see error messages if quality checks fail.
+
+### Before Declaring Complete
+
+**Never declare implementation complete without verification:**
+
+1. All code MUST pass quality gates (typecheck, lint, build)
+2. Tests MUST verify real behavior (T1-T4 rules - no mock-only tests)
+3. Changes MUST be verified by running them, not just implementing
+4. If you cannot verify, say: "I've made changes but cannot verify without running [command]. Please run and confirm."
+
+### T1-T4 Testing Rules
+
+| Rule | Requirement |
+|------|-------------|
+| T1 | Never mock the system under test |
+| T2 | Verify observable output, not function calls |
+| T3 | Integration tests use real systems |
+| T4 | Run tests before declaring complete |
+
+### Pipeline Orchestration
+
+For significant changes, you may be prompted to run review pipelines:
+- **Code Review** - Security, type safety, coding standards
+- **Test Audit** - T1-T4 compliance verification
+- **Fix Validation** - Root cause analysis and fix verification
+
+Follow pipeline instructions when prompted.
+
+### Your Role
+
+- Write production-grade code that passes quality checks
+- Use real behavior verification in tests
+- Verify implementations before declaring complete
+
+---
+
+## Project-Specific Rules
+
+<!--
+Users can add project-specific governance rules below.
+These will be injected into Claude's context at session start.
+
+NOTE: The core governance rules above should not be modified.
+This section is for project-specific additions only.
+
+Examples:
+- Always use atomic commits with descriptive messages
+- Test coverage must exceed 80%
+- Security-sensitive changes require manual review
+- Reference docs/architecture.md for design decisions
+-->