@qball-inc/the-bulwark 1.0.0

package/skills/setup-lsp/references/troubleshooting.md

@@ -0,0 +1,135 @@
+# LSP Troubleshooting Reference
+
+Reference data for diagnosing LSP configuration failures. Load this file during Stage 7 (Diagnostics) and whenever Stage 6 verification fails.
+
+---
+
+## Common Issues
+
+Work through issues in the order listed. Stop at the first issue that is detected and apply the fix before continuing.
+
+| # | Issue | Detection Method | Fix Procedure |
+|---|-------|-----------------|---------------|
+| 1 | `ENABLE_LSP_TOOL` not set | Run `echo $ENABLE_LSP_TOOL`. If output is empty or not `1`, flag is missing. | Add `export ENABLE_LSP_TOOL=1` to shell profile (`~/.bashrc` or `~/.zshrc`). Also set the key in `~/.claude/settings.json`. Then exit and resume session. |
+| 2 | Plugin not installed | Check `/plugin` Installed tab or run `claude plugin list` from a separate terminal. If plugin name is absent, plugin was not installed. | Tell user to install the plugin: type `/plugin`, search for the plugin name, and install it. Or from a separate terminal: `claude plugin install {plugin-name}`. |
+| 3 | Plugin installed but not enabled | Check `/plugin` Installed tab. If plugin appears but status is not "enabled", plugin is installed but inactive. | Tell user to enable the plugin: type `/plugin`, find the plugin, and enable it. Or from a separate terminal: `claude plugin enable {plugin-name}`. |
+| 4 | Debug log shows 0 servers loaded | Run `cat ~/.claude/debug/latest` and search for `Total LSP servers loaded`. If value is 0, servers did not initialize. | Confirm issues 1-3 are resolved. Tell user to exit Claude Code fully and resume the session. Check log again after resume — async loading race means first post-install resume sometimes fails. A second exit+resume resolves it. |
+| 5 | Server binary not in PATH | Run `which {binary-name}` (e.g., `which typescript-language-server`). If not found, binary is not installed or not in PATH. | Install the binary using the command from `references/server-registry.md`. If installed but not in PATH, add the install location to PATH in shell profile. |
+
+---
+
+## Known Behaviors (Not Defects)
+
+### Java JVM Warmup Delay
+
+The `jdtls` server (Java) takes approximately 8 seconds to initialize due to JVM startup overhead. This is normal. Other servers typically initialize in 0.5-0.6 seconds.
+
+If the debug log shows `Total LSP servers loaded: N` where N is less than expected and Java is one of the detected languages:
+- Wait 10-15 seconds after session resume.
+- Re-read `~/.claude/debug/latest`.
+- jdtls should appear once JVM warmup completes.
+
+Do not treat slow jdtls initialization as a failure unless it is absent after 20 seconds.
+
+### Async Loading Race on First Post-Install Resume
+
+After a fresh plugin install, the first session resume may show `Total LSP servers loaded: 0` even when configuration is correct. This is a known async loading race condition (community issue #10997).
+
+Detection: Configuration looks correct (issues 1-3 resolved), but first resume still shows 0 servers.
+
+Fix: Exit Claude Code and resume again. A second exit+resume consistently resolves this race.
+
+### "Executable not found in $PATH" in Plugin Errors Tab
+
+LSP plugins configure how Claude Code connects to a language server, but they don't include the server binary itself. If you see this error in the `/plugin` Errors tab, the binary needs to be installed separately (see server-registry.md for install commands).
+
+---
+
+## Debug Log Inspection
+
+The debug log is the primary diagnostic source for LSP initialization.
+
+**Log location:**
+```
+~/.claude/debug/latest
+```
+
+**Key lines to search for:**
+
+| Line Pattern | Meaning |
+|--------------|---------|
+| `Total LSP servers loaded: N` | N servers initialized successfully. N=0 means none loaded. |
+| `Initializing LSP server: {name}` | Server startup was attempted for this plugin. |
+| `LSP server {name} failed: {reason}` | Server startup was attempted but failed. Reason indicates root cause. |
+| `Plugin {name} enabled` | Plugin was found in enabled state at startup. |
+| `ENABLE_LSP_TOOL not set` | The environment flag is missing. Fix issue #1. |
+| `Executable not found in $PATH` | Language server binary is not installed. Fix issue #5. |
+
+**Useful search commands:**
+```bash
+# Check total servers loaded
+grep "Total LSP servers" ~/.claude/debug/latest
+
+# Check for any LSP-related log lines
+grep -i "lsp" ~/.claude/debug/latest
+
+# Check for plugin loading
+grep "Plugin" ~/.claude/debug/latest
+
+# Check for failures
+grep -i "failed\|error" ~/.claude/debug/latest
+```
+
+---
+
+## ENABLE_LSP_TOOL Verification
+
+`ENABLE_LSP_TOOL` is an undocumented flag required for LSP tool activation, discovered via community report (#15619). It must be set in two places:
+
+**1. Shell profile** (persists across terminal sessions):
+```bash
+# In ~/.bashrc or ~/.zshrc
+export ENABLE_LSP_TOOL=1
+```
+
+**2. `~/.claude/settings.json`** (read by Claude Code at startup):
+```json
+{
+  "ENABLE_LSP_TOOL": "1"
+}
+```
+
+To verify both locations are configured:
+```bash
+# Check shell profile
+grep "ENABLE_LSP_TOOL" ~/.bashrc ~/.zshrc 2>/dev/null
+
+# Check settings.json
+grep "ENABLE_LSP_TOOL" ~/.claude/settings.json
+```
+
+Both must return a match with value `1`. If either is missing, fix and exit+resume.
+
+---
+
+## enabledPlugins Format
+
+The `enabledPlugins` field in `~/.claude/settings.json` uses an object format with marketplace-qualified names:
+
+```json
+{
+  "ENABLE_LSP_TOOL": "1",
+  "enabledPlugins": {
+    "typescript-lsp@claude-plugins-official": true,
+    "pyright-lsp@claude-plugins-official": true
+  }
+}
+```
+
+**Common mistakes:**
+- Using binary names instead of plugin names (e.g., `typescript-language-server` instead of `typescript-lsp`)
+- Using an array format instead of object format
+- Omitting the `@claude-plugins-official` marketplace qualifier
+- Adding entries manually instead of letting `claude plugin install/enable` manage them
+
+**Best practice:** Let the `claude plugin install` and `claude plugin enable` commands manage `enabledPlugins` entries. Manual editing should only be used for troubleshooting.

package/skills/subagent-output-templating/SKILL.md

@@ -0,0 +1,415 @@
+---
+name: subagent-output-templating
+description: Template for structured sub-agent output including YAML log format, task completion reports (WHY/WHAT/TRADE-OFFS/RISKS), and summary constraints. Use when defining how sub-agents should report results.
+user-invocable: false
+---
+
+# Sub-Agent Output Templating
+
+## Overview
+
+This skill provides standardized templates for sub-agent OUTPUT formatting. It complements `subagent-prompting` (P0.1) which defines INPUT structure:
+
+| Skill | Purpose |
+|-------|---------|
+| `subagent-prompting` | How to prompt sub-agents (GOAL/CONSTRAINTS/CONTEXT/OUTPUT) |
+| `subagent-output-templating` | How sub-agents report results (logs, summaries, diagnostics) |
+
+Use this skill when:
+- Defining output requirements for sub-agent invocations
+- Parsing sub-agent results in pipeline stages
+- Ensuring consistent log formats across all agents
+
+---
+
+## Log File Format
+
+### File Location
+
+```
+logs/{agent-name}-{YYYYMMDD-HHMMSS}.yaml
+```
+
+Example: `logs/bulwark-code-auditor-20260111-143022.yaml`
+
+### YAML Schema
+
+```yaml
+# Required: Metadata block
+metadata:
+  agent: {agent-name}           # e.g., bulwark-code-auditor
+  timestamp: {ISO-8601}         # e.g., 2026-01-11T14:30:22Z
+  model: {model-used}           # sonnet, haiku, or opus
+  task_id: {unique-identifier}  # For tracking across pipeline stages
+  duration_ms: {execution-time} # Execution duration in milliseconds
+
+# Required: Goal from the prompt (for traceability)
+goal: "{GOAL from 4-part prompt}"
+
+# Required: Completion report
+completion:
+  why:
+    problem: "{What was broken/missing}"
+    root_cause: "{Why it happened}"
+    solution: "{What was implemented}"
+
+  what:
+    - file: {path}
+      lines: "{range}"
+      change: "{description}"
+
+  trade_offs:
+    gained:
+      - "{benefit 1}"
+    cost:
+      - "{drawback 1}"
+
+  risks:
+    - risk: "{description}"
+      mitigation: "{how addressed}"
+      severity: {low|medium|high|critical}
+
+  next_steps:
+    - "{action item 1}"
+
+# Required for code-writing agents (omit for read-only agents):
+# Pipeline suggestions from implementer-quality.sh output
+pipeline_suggestions:
+  - pipeline: "{recommended pipeline name}"
+    target_files:
+      - "{file path}"
+    reason: "{why this pipeline is recommended}"
+
+# Required: Summary for main thread (100-300 tokens)
+summary: |
+  {Concise summary for main thread consumption}
+
+# Required: Diagnostic output
+diagnostics:
+  model_requested: {model}
+  model_actual: {model}
+  context_type: {main|forked}
+  parent_vars_accessible: {true|false}
+  hooks_fired:
+    - {hook-name}
+  execution_time_ms: {duration}
+  completion_status: {success|error|timeout}
+```
+
+---
+
+## Task Completion Report (WHY/WHAT/TRADE-OFFS/RISKS)
+
+Every sub-agent MUST conclude with this structured report. This enables explicit decision documentation rather than implicit code changes.
+
+### WHY Section
+
+Document the problem and solution rationale.
+
+```yaml
+why:
+  problem: "Authentication bypass vulnerability in refresh token path"
+  root_cause: "Token validation skips expiry check on refresh"
+  solution: "Added isExpired() check to refresh token handler"
+```
+
+**Guidelines**:
+- `problem`: What was broken, missing, or needs improvement
+- `root_cause`: The underlying reason (not just symptoms)
+- `solution`: What was done to address it
+
+### WHAT Section
+
+List all changes made with file locations.
+
+```yaml
+what:
+  - file: src/auth/token.ts
+    lines: "45-52"
+    change: "Added isExpired() check before token refresh"
+  - file: src/auth/token.test.ts
+    lines: "120-145"
+    change: "Added test for expired refresh token rejection"
+```
+
+**Guidelines**:
+- One entry per file modified
+- Include line ranges for precise location
+- Describe the change, not the code
+
+### TRADE-OFFS Section
+
+Acknowledge explicit compromises made.
+
+```yaml
+trade_offs:
+  gained:
+    - "Security: Expired tokens now properly rejected"
+    - "Compliance: Meets OWASP session management requirements"
+  cost:
+    - "Performance: Additional DB lookup on refresh (negligible)"
+    - "Complexity: New error handling path for expired tokens"
+```
+
+**Guidelines**:
+- Be honest about costs
+- Quantify impact where possible
+- Include both technical and business trade-offs
+
+### RISKS Section
+
+Document forward-looking concerns.
+
+```yaml
+risks:
+  - risk: "Existing sessions with expired refresh tokens will fail"
+    mitigation: "Grace period of 24h for migration"
+    severity: medium
+  - risk: "Grace period could be exploited"
+    mitigation: "Monitor for unusual refresh patterns"
+    severity: low
+```
+
+**Severity Levels**:
+| Level | Definition |
+|-------|------------|
+| `low` | Unlikely or minor impact |
+| `medium` | Possible impact, manageable |
+| `high` | Likely impact, needs attention |
+| `critical` | Must be addressed before deployment |
+
+### NEXT STEPS Section
+
+List follow-up actions for pipeline or human.
+
+```yaml
+next_steps:
+  - "Monitor refresh failure rate for 24h"
+  - "Remove grace period after migration window"
+  - "Update documentation for new error codes"
+```
+
+**Guidelines**:
+- Actionable items only
+- Include owner if known (e.g., "DevOps: Update monitoring dashboard")
+- Order by priority
+
+---
+
+## Summary Format for Main Thread
+
+### Purpose
+
+The summary is returned to the main thread for pipeline decision-making. It should enable the orchestrator to:
+1. Understand key findings without reading full log
+2. Decide next pipeline stage
+3. Report status to user
+
+### Token Budget
+
+| Complexity | Target Tokens | Use Case |
+|------------|---------------|----------|
+| Simple | 100-150 | Single finding, clear action |
+| Moderate | 150-250 | Multiple findings, some nuance |
+| Complex | 250-300 | Many findings, trade-off decisions |
+
+### Summary Template
+
+```
+Found [N] [severity] issue(s): [brief description].
+[Action taken / recommendation].
+[Key risk or follow-up if any].
+```
+
+### Examples
+
+**Simple (120 tokens)**:
+```
+Found 1 critical vulnerability: refresh tokens not validated for expiry.
+Fixed by adding isExpired() check in token.ts:45-52. Added regression test.
+Risk: existing sessions may fail during 24h migration window.
+```
+
+**Moderate (200 tokens)**:
+```
+Found 3 issues in authentication module:
+- 1 critical: token expiry bypass (fixed)
+- 1 medium: weak password hashing (fixed, migration needed)
+- 1 low: verbose error messages (fixed)
+
+All issues addressed with tests added. Migration script created for password re-hashing.
+Next: run migration in staging, monitor for 48h before production.
+```
+
+### What to Include
+
+- Finding count and severity
+- Actions taken
+- Key risks or blockers
+- Recommended next steps
+
+### What to Exclude
+
+- Full reasoning or analysis
+- Code snippets
+- Verbose explanations
+- Duplicate information from log
+
+### Pipeline Suggestions in Summary (Code-Writing Agents)
+
+Code-writing agents (e.g., bulwark-implementer) that invoke `implementer-quality.sh` and receive pipeline suggestions MUST include them in the summary with MANDATORY language. This ensures the orchestrator sees and acts on them per SA6.
+
+```
+MANDATORY FOLLOW-UP (SA6): Run the following pipeline(s):
+  - {pipeline} on {target_files} ({reason})
+Orchestrator MUST evaluate each suggestion and either execute or document deferral per SA6.
+```
+
+Read-only agents (reviewers, auditors) omit this section.
+
+---
+
+## Diagnostic Output
+
+### Purpose
+
+Enable automated behavioral testing without mocking. Diagnostics verify:
+- Correct model was used
+- Context isolation worked (for `context: fork` agents)
+- Hooks fired as expected
+- Execution completed successfully
+
+### Location
+
+```
+logs/diagnostics/{agent-name}-{YYYYMMDD-HHMMSS}.yaml
+```
+
+### Format
+
+```yaml
+skill: subagent-output-templating
+timestamp: 2026-01-11T14:30:22Z
+diagnostics:
+  model_requested: sonnet
+  model_actual: sonnet
+  context_type: forked      # main or forked
+  parent_vars_accessible: false  # Should be false for forked
+  hooks_fired:
+    - Stop
+  execution_time_ms: 4520
+  completion_status: success  # success, error, timeout
+notes: "Task completed successfully"
+```
+
+### Diagnostic Fields
+
+| Field | Purpose | Values |
+|-------|---------|--------|
+| `model_requested` | Model specified in prompt | haiku, sonnet, opus |
+| `model_actual` | Model that actually ran | haiku, sonnet, opus |
+| `context_type` | Execution context | main, forked |
+| `parent_vars_accessible` | Context isolation test | true, false |
+| `hooks_fired` | Lifecycle hooks that executed | Array of hook names |
+| `execution_time_ms` | Duration | Integer |
+| `completion_status` | Final status | success, error, timeout |
+
+---
+
+## Quick Reference
+
+### Minimal Log Template
+
+```yaml
+metadata:
+  agent: {name}
+  timestamp: {ISO-8601}
+  model: sonnet
+  task_id: "{id}"
+  duration_ms: 0
+
+goal: "{goal}"
+
+completion:
+  why:
+    problem: "{problem}"
+    root_cause: "{cause}"
+    solution: "{solution}"
+  what:
+    - file: {path}
+      lines: "{range}"
+      change: "{description}"
+  trade_offs:
+    gained: ["{benefit}"]
+    cost: ["{cost}"]
+  risks:
+    - risk: "{risk}"
+      mitigation: "{mitigation}"
+      severity: medium
+  next_steps:
+    - "{action}"
+
+# Include for code-writing agents only (omit for read-only agents):
+pipeline_suggestions:
+  - pipeline: "{pipeline name}"
+    target_files: ["{path}"]
+    reason: "{reason}"
+
+summary: |
+  {100-300 token summary}
+
+diagnostics:
+  model_requested: sonnet
+  model_actual: sonnet
+  context_type: forked
+  parent_vars_accessible: false
+  hooks_fired: []
+  execution_time_ms: 0
+  completion_status: success
+```
+
+### Summary Checklist
+
+```
+[ ] Count and severity of findings stated
+[ ] Actions taken described
+[ ] Key risks mentioned
+[ ] Next steps listed
+[ ] Under 300 tokens
+[ ] Pipeline suggestions with MANDATORY language (code-writing agents only)
+```
+
+### Output Location Checklist
+
+```
+[ ] Main log: logs/{agent}-{YYYYMMDD-HHMMSS}.yaml
+[ ] Diagnostics: logs/diagnostics/{agent}-{YYYYMMDD-HHMMSS}.yaml
+```
+
+---
+
+## Timestamp Formats
+
+| Context | Placeholder | Format | Example |
+|---------|-------------|--------|---------|
+| **File paths** | `{YYYYMMDD-HHMMSS}` | Compact, filesystem-safe | `20260119-143022` |
+| **YAML fields** | `{ISO-8601}` | Standard ISO format | `2026-01-19T14:30:22Z` |
+
+**Why two formats?**
+- File names: No colons (filesystem-safe on Windows), compact, lexically sortable
+- YAML fields: Standard ISO-8601 for parsing and interoperability
+
+**Important**: Always use `{YYYYMMDD-HHMMSS}` in file paths, never `{timestamp}` or `{ts}`.
+
+---
+
+## Related Skills
+
+- **subagent-prompting** (P0.1): Defines INPUT structure (GOAL/CONSTRAINTS/CONTEXT/OUTPUT)
+- **pipeline-templates** (P0.3): Pre-defined workflows that consume this output format
+
+---
+
+## References
+
+For extended examples and edge cases, see `references/examples.md`.