feat: PR comment bot

.claude/skills/design-an-interface/SKILL.md

@@ -0,0 +1,22 @@
+# design-an-interface — integrations
+
+Three parallel designs, pick the deepest.
+
+## For GitHub Action inputs
+
+Design A: minimal — least the caller must know
+Design B: explicit — every option surfaced
+Design C: config-file-first — bawbel.yml drives, inputs are overrides
+
+## For VS Code TypeScript
+
+Design A: scan() returns everything, caller renders
+Design B: scan() + diagnose(), caller assembles
+Design C: event-driven — scan emits, providers subscribe
+
+## Constraints
+
+- Action inputs must have sensible defaults (most repos: zero config)
+- TypeScript interfaces must match bawbel JSON contract exactly
+- No input requiring caller to know bawbel internals
+- GracefulDegradation: every module handles missing bawbel CLI

.claude/skills/diagnose/SKILL.md

@@ -0,0 +1,24 @@
+# diagnose — integrations
+
+Reproduce → Minimize → Hypothesize → Fix.
+
+## Component-specific
+
+action.yml not reading bawbel.yml:
+  Check: does bawbel.yml exist in the scanned repo?
+  Check: is step output read correctly (${{ steps.config.outputs.* }})?
+
+VS Code not showing diagnostics:
+  Check: is bawbel installed? (which bawbel)
+  Check: is file type in activationEvents?
+  Run: bawbel scan <file> --format json in terminal to check output.
+
+Pre-commit wrong exit code:
+  Check: what does bawbel scan return for the test file?
+  Run: python bawbel_pre_commit.py <test_file> directly.
+
+## Standard loop
+
+Reproduce → Minimize (5-15 lines) → Hypothesize (ONE hypothesis) →
+Confirm → Fix (1-5 lines) → Verify (test + full suite) →
+Regression test → Remove debug output → WHY comment.

.claude/skills/git-guardrails/SKILL.md

@@ -0,0 +1,18 @@
+# git-guardrails — integrations
+
+Block dangerous commands. Ask before: push --force, reset --hard,
+clean -fd, rebase -i on pushed commits.
+
+## Before every commit
+
+pytest tests/ -x -q
+cd vscode && npm test
+ruff check bawbel_hooks/
+cd vscode && npm run lint
+
+## Release checklist
+
+- [ ] action.yml version in README matches tag
+- [ ] vscode/package.json version matches tag
+- [ ] CHANGELOG.md updated
+- [ ] bawbel-scanner constraint in action.yml is current

.claude/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,32 @@
+# grill-with-docs — integrations
+
+Grilling before design. No code until complete.
+
+## Pre-check questions (integrations-specific)
+
+Q0: Which component? action.yml / vscode/ / bawbel_hooks/ / all three?
+    If all three: probably too large — split the scope.
+
+Q1: Does this change the bawbel CLI JSON contract?
+    If yes: coordinate with bawbel/scanner first.
+
+Q2: Which language and test framework?
+    Python → pytest / TypeScript → npm test / shell → bash
+
+Q3: Does this affect the three ADRs?
+    ADR-0001: SARIF only, no code injection
+    ADR-0002: PR comment updates in-place
+    ADR-0003: VS Code GracefulDegradation
+
+## Standard questions
+
+Q4: One sentence — what does this change do?
+Q5: What does "done" look like? How do you verify it?
+Q6: What breaks if bawbel is not installed?
+Q7: What breaks if the bawbel JSON shape changes?
+Q8: What is the first failing test name?
+
+## End of grilling
+
+Summary, interface, LANGUAGE.md additions, ADR if needed, first test.
+Next: /to-prd

.claude/skills/handoff/SKILL.md

@@ -0,0 +1,32 @@
+# handoff — integrations
+
+End of session: write docs/agents/handoffs/YYYY-MM-DD-HHMM.md
+Start of session: read most recent, run tests.
+
+## End format
+
+# Handoff — YYYY-MM-DD HH:MM
+
+## Completed
+- action.yml:L45-L80 — bawbel.yml config step added
+- tests/action/test_config_loading.sh — 3 tests
+
+## Test status
+pytest tests/ -q     → N passed
+cd vscode && npm test → N passed
+
+## Next action
+Component: vscode/
+File: vscode/src/panels/AIVSSPanel.ts
+Test to write first:
+```typescript
+it('shows AIVSS score from finding', () => {
+    const finding = makeFinding({ aivss_score: 8.4 });
+    expect(renderPanel(finding)).toContain('8.4');
+});
+```
+
+## Open questions
+- Does AIVSSPanel need PiranhaDB or just local finding data?
+
+Note: docs/agents/handoffs/ is gitignored.

.claude/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,24 @@
+# improve-codebase-architecture — integrations
+
+Find deepening opportunities. Use the deletion test.
+
+## Current candidates
+
+action.yml inline Python:
+- PR comment formatting — inline, could be a deep function
+- Config resolution — inline bash, could have clearer interface
+
+vscode/ candidates:
+- BawbelScanner.ts — is it doing too much?
+- DiagnosticProvider.ts — is severity mapping mixed with range calc?
+
+## Deletion test
+
+"If I deleted this module, would callers re-implement the logic?"
+Yes → earning its keep → deepen it.
+No → pass-through → simplify or delete.
+
+## Language
+
+module, interface, depth, seam, adapter.
+NOT: component, plugin, middleware.

.claude/skills/setup-bawbel-integrations/SKILL.md

@@ -0,0 +1,32 @@
+# setup-bawbel-integrations
+
+Run once before using any other skill.
+
+## Steps
+
+1. Read CLAUDE.md — confirm three components, current task queue
+2. Read LANGUAGE.md — confirm domain terms (Action, Extension, Hook)
+3. Read ARCHITECTURE.md — confirm component map and CLI contract
+4. Check docs/adr/ for decisions already made
+
+## Install Matt Pocock's skills
+
+```bash
+npx skills@latest add mattpocock/skills/tdd
+npx skills@latest add mattpocock/skills/to-prd
+npx skills@latest add mattpocock/skills/to-issues
+npx skills@latest add mattpocock/skills/grill-with-docs
+npx skills@latest add mattpocock/skills/design-an-interface
+npx skills@latest add mattpocock/skills/handoff
+npx skills@latest add mattpocock/skills/zoom-out
+```
+
+## Key context
+
+Three components, three languages:
+- action.yml — shell + Python (tested via act or manual CI)
+- vscode/ — TypeScript + Node.js (npm test)
+- bawbel_hooks/ — Python (pytest tests/hooks/)
+
+All three share one contract: bawbel scan --format json output shape.
+If that shape changes in bawbel/scanner, all three need updating.

.claude/skills/tdd/SKILL.md

@@ -0,0 +1,55 @@
+# tdd — bawbel/integrations
+
+Red-green-refactor. One behavior at a time.
+Three languages — three testing approaches.
+
+## Python (bawbel_hooks/)
+
+```bash
+pytest tests/hooks/test_pre_commit.py::test_name -x -q  # FAIL
+# implement
+pytest tests/hooks/test_pre_commit.py::test_name -x -q  # PASS
+pytest tests/ -x -q                                       # full suite
+```
+
+## TypeScript (vscode/)
+
+```bash
+cd vscode/
+npm test -- --grep "test name"  # FAIL
+# implement
+npm test -- --grep "test name"  # PASS
+npm test                         # full suite
+```
+
+## What/Why/How — mandatory on every function
+
+Python:
+```python
+# What: posts or updates a Bawbel scan summary comment on a pull request
+# Why:  re-running a scan should update existing comment, not create noise
+# How:  lists PR comments, finds "Bawbel Scanner", PATCHes or POSTs
+def post_pr_comment(token, repo, pr_number, body):
+    ...
+```
+
+TypeScript:
+```typescript
+// What: converts a bawbel severity string to VS Code DiagnosticSeverity
+// Why:  VS Code requires its own enum, not bawbel string values
+// How:  switch on severity string, defaults to Warning for unknown values
+function toVSCodeSeverity(severity: string): vscode.DiagnosticSeverity {
+    ...
+}
+```
+
+Write the comment BEFORE writing the function body.
+
+## Test naming
+
+test_[component]_[behavior]_when_[condition]
+
+## Key rule
+
+Tests must NOT call the real bawbel CLI.
+Mock the subprocess call or use fixture JSON files.

.claude/skills/tdd/deep-modules.md

@@ -0,0 +1,11 @@
+# Deep modules — integrations context
+
+VS Code modules that should be deep:
+- BawbelScanner: one call → findings[]
+  Hides: subprocess, timeout, error handling, JSON parsing
+- DiagnosticProvider: one call → DiagnosticCollection updated
+  Hides: range calc, severity mapping, collection management
+
+Deletion test:
+If you deleted BawbelScanner, the subprocess complexity would
+reappear in every caller. It earns its keep — keep it deep.

.claude/skills/to-issues/SKILL.md

@@ -0,0 +1,17 @@
+# to-issues — integrations
+
+Break PRD into independently-completable GitHub issues.
+One behavior, one test, one component, completable in < 90 min.
+
+## Component ordering
+
+For features touching multiple components:
+1. bawbel_hooks/ (Python — fastest to test)
+2. action.yml (shell — medium)
+3. vscode/ (TypeScript — most complex)
+
+## Issue body additions
+
+Add to every issue:
+Component: vscode/
+Test command: cd vscode && npm test -- --grep "test name"

.claude/skills/to-prd/SKILL.md

@@ -0,0 +1,11 @@
+# to-prd — integrations
+
+Save to docs/agents/prds/prd-NN-[slug].md. Create a GitHub issue.
+
+## Additional fields for this repo
+
+Component: action.yml | vscode/ | bawbel_hooks/ | cross-component
+CLI contract change: yes (coordinate with bawbel/scanner) | no
+Test command: pytest / npm test / bash
+
+Otherwise use the same PRD format as bawbel/scanner.

.claude/skills/zoom-out/SKILL.md

@@ -0,0 +1,14 @@
+# zoom-out — integrations
+
+Read before editing. Do NOT edit during zoom-out.
+
+1. Which component? (action.yml / vscode/ / bawbel_hooks/)
+2. ARCHITECTURE.md — where in the flow diagram?
+3. LANGUAGE.md — what terms apply?
+4. docs/adr/ — any decisions constraining this?
+5. What depends on this? What does it depend on?
+6. What happens if bawbel is not installed?
+
+For action.yml: read step names in order, find which step you are editing.
+For vscode/: read extension.ts activate() to see what is registered.
+For bawbel_hooks/: read .pre-commit-hooks.yaml to see what is called.

.github/workflows/bawbel-scan.yml

@@ -0,0 +1,33 @@
+name: Bawbel Security Scan
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  scan:
+    name: Scan for AVE vulnerabilities
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      contents: read
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Bawbel Scanner
+        uses: bawbel/integrations@pr-commit-bot
+        with:
+          path: ./tes_skill.md
+          fail-on-severity: high
+          comment-on-pr: true
+          github-token: ${{ secrets.MY_GH_TOKEN }}
+
+      - name: Upload SARIF to GitHub Security
+        uses: github/codeql-action/upload-sarif@v4
+        if: always()
+        with:
+          sarif_file: bawbel-results.sarif

.gitignore

@@ -1,3 +1,27 @@
-vscode/out/
+# Python
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+
+# Node
 vscode/node_modules/
-**/*.vsix
+vscode/out/
+vscode/*.vsix
+
+# Bawbel session notes
+docs/agents/handoffs/
+
+# Environment
+.env
+
+# OS
+.DS_Store
+
+# ── Private context files — never commit these ────────────────────────────────
+# These contain business strategy, roadmap, and founder context.
+# Keep them local only. Share via secure channel if needed.
+PROJECT_CONTEXT.md
+HOW-TO-USE.md
+.claude/