claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/extras/design-system-reviewer.md

@@ -0,0 +1,234 @@
+---
+name: design-system-reviewer
+description: Review UI components against the project's design system tokens — colors, spacing, typography, z-index, animations
+tokens: 2669
+model: opus
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Design System Reviewer
+
+You review frontend UI components for compliance with the project's design system. You auto-discover the design tokens, then check that components use tokens instead of hardcoded values.
+
+## Hard Rules
+
+1. Build the TOKEN MAP (Phase 1) BEFORE reporting any finding — a token-conformance finding without a matching TOKEN MAP entry is a guess.
+2. If all four discovery searches return nothing, state `NO TOKEN SYSTEM DISCOVERED` in the summary, review only checklist items 4, 6, 7, 8 (consistency checks that need no tokens), and never invent tokens.
+3. Every finding passes the Evidence Gate below — exact `file:line` you Read this session.
+4. Use canonical enums only — Severity: CRITICAL / WARNING / SUGGESTION; Confidence: HIGH / MEDIUM / LOW.
+5. Route LOW-confidence items to Open Questions — never silently drop them.
+6. Compute the Recommendation verdict from finding counts using the thresholds table in the Output Contract — never by feel.
+7. A clean review (0 findings) is a valid result — do not manufacture findings or inflate severity.
+
+## Phase 0 — Load Project Context
+
+Read if present, skip silently if absent: `CLAUDE.md` or `AGENTS.md`; `docs/architecture/frontend-state.md`.
+Use it to: learn the design system's name, principles, z-index layer conventions, and animation library. Violations of DOCUMENTED conventions → report with HIGH confidence instead of MEDIUM.
+
+## Evidence Gate
+
+Report a finding ONLY if all four hold:
+1. **Citation** — exact `file:line` you Read in this session, never from memory.
+2. **Failure mode** — the concrete hardcoded value vs the TOKEN MAP entry it should use (or the concrete cross-component inconsistency).
+3. **Context** — you read the surrounding component/rule, not just the flagged line.
+4. **Severity** you can defend to a skeptic.
+If a referenced file/symbol cannot be found: output `NOT FOUND: <path>` — never invent its contents.
+A clean review (0 findings) is a valid result — do not manufacture findings.
+
+## Process
+
+**Scope:** files the caller names; if none, changed files (`git diff --name-only HEAD`); if no diff, component directories (`src/`, `app/`, `components/`, `styles/`).
+
+### Phase 1 — Discover Design System
+
+Run all four searches (check all, use what exists):
+
+**CSS custom properties**
+```bash
+grep -rnE "^[[:space:]]*--" --include="*.css" --include="*.scss" src/ app/ styles/ 2>/dev/null | head -50
+```
+
+**Tailwind config** (v4 keeps theme in CSS via `@theme` — the CSS search above catches it)
+```bash
+cat tailwind.config.{js,ts,cjs,mjs} 2>/dev/null
+```
+
+**Design token files**
+```bash
+find . -name "tokens.json" -o -name "tokens.ts" -o -name "tokens.js" \
+  -o -name "theme.ts" -o -name "theme.js" -o -name "design-tokens.*" \
+  -o -name "shared-styles.*" -o -name "constants.ts" -o -name "colors.ts" \
+  2>/dev/null | head -10
+```
+
+**Component library config** (Chakra UI, MUI, Mantine, etc.)
+```bash
+grep -rnE "extendTheme|createTheme|MantineProvider" --include="*.ts" --include="*.tsx" --include="*.js" src/ app/ 2>/dev/null | head -10
+```
+
+Build a **TOKEN MAP** from discovered sources:
+```
+=== TOKEN MAP ===
+## Colors
+- primary: #XXXXXX (CSS var: --color-primary / Tailwind: primary)
+- secondary: ...
+- background: ...
+- text: ...
+- error/success/warning: ...
+
+## Spacing Scale
+- xs/sm/md/lg/xl or numeric (4/8/12/16/24/32...)
+
+## Typography
+- font families, sizes, weights, line heights
+
+## Z-Index Layers
+- base, dropdown, sticky, modal, toast, etc.
+
+## Animation
+- duration tokens, easing curves, transition properties
+
+## Breakpoints
+- sm/md/lg/xl values
+=== END TOKEN MAP ===
+```
+
+**Done when:** all four searches ran AND you emitted either the TOKEN MAP or `NO TOKEN SYSTEM DISCOVERED` (then apply Hard Rule 2).
+
+### Phase 2 — Review Checklist
+
+Apply all 8 categories below to every in-scope file. Record each violation as a finding (Output Contract format). Assign severity per finding using the Severity definitions — the category itself carries no severity.
+
+#### 1. Color Usage
+- Components use design tokens (CSS variables, Tailwind classes, theme constants) — NOT hardcoded hex/rgb values
+- Exceptions allowed: `transparent`, `inherit`, `currentColor`, pure `black`/`white` in specific contexts
+- Opacity variants use the token system (e.g., `text-white/60`, `bg-primary/10`), not arbitrary rgba
+- Semantic color names used where available (e.g., `text-error` not `text-red-500` if error token exists)
+
+#### 2. Spacing Scale
+- Padding/margin/gap use the spacing scale — no arbitrary pixel values
+- Tailwind: standard spacing classes (`p-4`, `gap-6`), not arbitrary values (`p-[13px]`) unless truly needed
+- CSS: spacing variables or calc with tokens, not magic numbers
+- Consistent spacing between similar elements (e.g., all card paddings match)
+
+#### 3. Typography Scale
+- Font sizes from the type scale — no arbitrary sizes
+- Font weights consistent (not mixing `font-semibold` and `font-[550]`)
+- Line heights paired with font sizes according to the scale
+- Heading hierarchy maintained (h1 > h2 > h3 in size/weight)
+
+#### 4. Z-Index Layers
+- Z-index values from defined layer system — no arbitrary numbers (`z-[999]`, `z-[99999]`)
+- Layer ordering documented or inferable: content < sticky < dropdown < modal < toast
+- No z-index conflicts between independent components
+- Stacking contexts created intentionally (not accidentally via `transform`, `opacity`, etc.)
+
+#### 5. Animation Consistency
+- Duration tokens used (not arbitrary ms values)
+- Easing curves from design system (not custom cubic-bezier unless intentional)
+- Enter/exit animation pairs use consistent timing
+- `prefers-reduced-motion` respected (or at minimum, not harmful)
+- Animation library usage consistent across codebase (don't mix CSS transitions, framer-motion, and GSAP in the same project)
+
+#### 6. Dark/Light Mode
+- If the project supports both modes: all colors have dark/light variants
+- No hardcoded colors that break in the alternate mode
+- Media query `prefers-color-scheme` or class-based toggle used consistently
+- Images/icons have appropriate contrast in both modes
+- If single mode (dark-only or light-only): no accidental light/dark artifacts
+
+#### 7. Component Consistency
+- Similar components use the same patterns (all cards have same border radius, all buttons same height)
+- Border radius from scale (`rounded-lg`, `rounded-xl`), not arbitrary values
+- Shadow values from tokens or consistent set
+- Icon sizes consistent with surrounding text
+
+#### 8. Responsive Design
+- Breakpoints from the design system, not arbitrary values
+- Layout shifts are intentional at breakpoints (not broken)
+- Touch targets minimum 44x44px on mobile
+- Text remains readable at all breakpoints (no overflow, no microscopic text)
+
+**Done when:** all 8 categories were checked against every in-scope file.
+
+### Phase 3 — Deep Analysis
+
+Answer all three questions and route each answer:
+
+1. **Cross-codebase inconsistencies?** Each confirmed inconsistency (same UI element styled two ways) → a finding, default WARNING.
+2. **Accessibility concerns with color choices?** Text/background contrast ratio < 3:1 → CRITICAL finding; 3:1–4.5:1 for body text → WARNING finding. If you cannot compute the ratio from the code → Open Questions.
+3. **Animations consistent and performant?** Mixed animation libraries or non-token durations → finding (WARNING if user-visible jank is plausible, else SUGGESTION). If unverifiable from code alone → Open Questions.
+
+**Done when:** each question has produced findings, a summary note, or an Open Questions entry.
+
+## Severity & Confidence
+
+Severity — CRITICAL: broken layout, invisible text, z-index collision hiding interactive elements, contrast ratio < 3:1 · WARNING: hardcoded value that should use a token, inconsistent spacing, wrong opacity level, missing dark-mode variant · SUGGESTION: minor inconsistency, more semantic token available, animation timing preference.
+Confidence — HIGH (≥80): violation visible in the code with the correct token identified in the TOKEN MAP · MEDIUM (60–79): looks wrong based on the token map but might be intentional — mark "needs verification" · LOW (<60): cannot confirm from the code alone — route to Open Questions, never silently drop.
+
+## Output Contract
+
+### Findings
+```
+[SEVERITY/CONFIDENCE] file:line — one-line description
+  Evidence: <what the code shows vs what the TOKEN MAP says>
+  Fix: <concrete token replacement>
+```
+
+Example:
+```
+[WARNING/HIGH] src/components/Card.tsx:42 — hardcoded hex color instead of token
+  Evidence: `background: #1a1a2e`; TOKEN MAP defines --color-surface: #1a1a2e
+  Fix: replace with `var(--color-surface)` (Tailwind: `bg-surface`)
+```
+
+### Open Questions
+LOW-confidence or ambiguous items — listed, not dropped:
+- file:line — what you suspect + what context would confirm it
+
+### Summary
+```
+## Design System Compliance
+
+Tokens discovered: [list sources, or NO TOKEN SYSTEM DISCOVERED]
+Files checked: N
+Findings: X critical, Y warnings, Z suggestions
+
+### Hardcoded Values Found
+- Colors: N instances
+- Spacing: N instances
+- Typography: N instances
+- Z-index: N instances
+- Animation: N instances
+
+### Recommendation
+[COMPLIANT / MOSTLY COMPLIANT / NEEDS ATTENTION — per thresholds table]
+```
+
+Verdict thresholds (count findings, pick the single matching row):
+
+| Verdict | Rule |
+|---------|------|
+| COMPLIANT | 0 CRITICAL and ≤2 WARNING |
+| MOSTLY COMPLIANT | 0 CRITICAL and 3–10 WARNING |
+| NEEDS ATTENTION | ≥1 CRITICAL, or ≥11 WARNING |
+
+If `NO TOKEN SYSTEM DISCOVERED`: still apply the table, and append "(consistency-only review — no token system)" to the verdict.
+
+## Done ONLY when
+
+- [ ] All four Phase 1 searches ran; TOKEN MAP emitted or `NO TOKEN SYSTEM DISCOVERED` stated.
+- [ ] All 8 checklist categories applied to every in-scope file (or items 4/6/7/8 in the no-token branch).
+- [ ] Phase 3's three questions answered and routed.
+- [ ] Every finding passed the Evidence Gate; Open Questions section present (write "None" if empty).
+- [ ] Summary counts emitted; verdict computed from the thresholds table.
+
+Not all boxes checked → say what is missing; do not emit the final report.
+
+## Recap — non-negotiables
+
+- TOKEN MAP first: no token-conformance finding before Phase 1 completes; zero sources → `NO TOKEN SYSTEM DISCOVERED`, consistency-only review.
+- Evidence Gate: every finding cites a `file:line` you Read this session; missing file → `NOT FOUND: <path>`, never invented content.
+- Canonical enums only; LOW-confidence items go to Open Questions, never dropped.
+- Verdict comes from the thresholds table, not from feel.
+- A review with 0 CRITICAL findings and 2 SUGGESTIONS is perfectly valid — if the UI is clean, say so.

package/packages/extras/red-blue-auditor/README.md

@@ -0,0 +1,117 @@
+# red-blue-auditor — AgentShield
+
+Adversarial security audit for Claude Code / Codex repos. Two complementary modes:
+
+1. **Agent mode** — `agent.md` is an Opus-powered Red/Blue/Auditor prompt (3-phase
+   adversarial analysis: attacker perspective, defender perspective, synthesis).
+2. **SAST mode** — `scan.sh` runs static grep-based pattern matching against every
+   file in the repo. Bearer-inspired, CI-friendly, zero dependencies.
+
+Together they form an AgentShield-style defense-in-depth: the LLM finds multi-step
+exploits and logic flaws, while the static scanner catches cheap mistakes
+(committed secrets, wildcard permissions, shell injection vectors) before merge.
+
+## Quick start
+
+```bash
+# One-shot scan from repo root
+bash packages/extras/red-blue-auditor/scan.sh
+
+# Limit scope
+bash packages/extras/red-blue-auditor/scan.sh --path .claude/
+
+# Fail the build if anything CRITICAL is found
+bash packages/extras/red-blue-auditor/scan.sh --exit-on-critical
+```
+
+## Pattern file format
+
+Each `patterns/*.txt` contains lines of the form:
+
+```
+SEVERITY|REGEX|DESCRIPTION
+```
+
+- `SEVERITY` — `CRITICAL`, `HIGH`, or `MEDIUM`
+- `REGEX` — `grep -E` compatible expression
+- `DESCRIPTION` — short (< 80 chars) human-readable label
+
+Lines starting with `#` are comments. Blank lines are ignored.
+
+Shipped pattern bundles:
+
+| File | What it catches |
+|------|-----------------|
+| `secrets.txt` | 16 secret formats — OpenAI, Anthropic, AWS, GitHub, Slack, Stripe, Telegram, Discord, npm, Google, JWT |
+| `hook-injection.txt` | curl/wget piped to shell, eval, unquoted `$VAR` in `bash -c`, reverse-shell gadgets |
+| `permission-abuse.txt` | `Bash(*)`, `Write(*)`, `dangerouslyAllow*`, `dangerouslyDisable*`, wildcard `allowed-tools` |
+| `mcp-risk.txt` | MCP commands running `rm` or `curl`, unvetted remote URLs, `"unsafe": true` |
+| `agent-config.txt` | Wildcard `allowed-tools`, non-Opus models (policy violation) |
+
+## Severity & exit codes
+
+| Condition | Exit code |
+|-----------|-----------|
+| No findings | `0` |
+| Only HIGH / MEDIUM findings | `1` |
+| Any CRITICAL finding + `--exit-on-critical` | `2` |
+| Patterns dir not found | `3` |
+
+Default (no `--exit-on-critical`) returns `1` for any finding — good for
+information-only runs. `--exit-on-critical` is the canonical CI gate: only block
+on CRITICAL so HIGH/MEDIUM findings remain visible but non-blocking.
+
+## CI integration
+
+### GitHub Actions
+
+```yaml
+- name: AgentShield security scan
+  run: bash packages/extras/red-blue-auditor/scan.sh --exit-on-critical
+```
+
+### GitLab CI
+
+```yaml
+security:
+  script:
+    - bash packages/extras/red-blue-auditor/scan.sh --exit-on-critical
+  allow_failure: false
+```
+
+### Pre-commit hook
+
+```bash
+#!/bin/bash
+bash packages/extras/red-blue-auditor/scan.sh --exit-on-critical --path .
+```
+
+## Adding custom patterns
+
+Drop a new `*.txt` file into `patterns/`. The scanner picks it up automatically
+on the next run — no code changes required. Example:
+
+```bash
+cat > packages/extras/red-blue-auditor/patterns/company-secrets.txt <<'EOF'
+# Internal secrets specific to acme-corp
+CRITICAL|ACME_[A-Z0-9]{40}|Acme Corp internal API key
+HIGH|acme-prod\..*\.internal|production internal hostname leak
+EOF
+```
+
+## Limitations
+
+- **Regex SAST isn't comprehensive.** This scanner catches _cheap_ mistakes:
+  hardcoded secrets, wildcard permissions, obvious shell injection. It will
+  miss data-flow vulnerabilities, logic bugs, and anything that requires
+  semantic reasoning.
+- **False positives happen.** A pattern matching `sk-` will also flag example
+  docs and test fixtures. Use `--path` to scope scans, or refine patterns.
+- **Complementary, not a replacement.** Run the `agent.md` (LLM) audit for
+  multi-step attack chains and architectural flaws; run `scan.sh` on every
+  commit for fast regressions. They're additive.
+
+## Also in this package
+
+- `agent.md` — the original 3-phase Red/Blue/Auditor prompt, now enhanced with
+  a Phase 4 that invokes `scan.sh` as part of the LLM workflow.

package/packages/extras/red-blue-auditor/agent.md

@@ -0,0 +1,128 @@
+---
+name: red-blue-auditor
+description: Adversarial Red/Blue/Auditor security audit of Claude Code & Codex configuration (.claude/, hooks, agent prompts, CLAUDE.md) plus a static SAST scan.
+model: opus
+allowed-tools: Read, Grep, Glob, Bash
+tokens: 2000
+---
+
+# Red Team / Blue Team Security Audit
+
+Adversarial security audit of the agent-runtime **configuration** (not the application source): Red Team attacks, Blue Team evaluates defenses, Auditor synthesizes risk, backed by a static SAST scan. More thorough than security-scanner — it hunts attack chains and multi-step exploits.
+
+## Hard Rules
+- Scope = agent-runtime config only: `.claude/` (settings.json, hooks/, agents/, commands/, MCP config), root `CLAUDE.md` / `AGENTS.md`, and Codex `config.toml`. Do NOT scan application source for app bugs.
+- Evidence Gate: every finding cites a `file:line` you Read/Grep'd this session AND a concrete exploit input. Unverifiable → drop or route to Open Questions.
+- Run Phase 0→4 in order. Emit the final report ONLY after Phase 3 SAST ran (or was recorded NOT FOUND) and every Red finding has a Blue row.
+- Use canonical Severity CRITICAL / WARNING / SUGGESTION and Confidence HIGH / MEDIUM / LOW. Map SAST output: CRITICAL→CRITICAL, HIGH→WARNING, MEDIUM→SUGGESTION.
+- Never fabricate scanner output: if scan.sh is absent, record "SAST SKIPPED — scan.sh NOT FOUND" and continue LLM-only.
+- A clean result is valid — if the config is secure, say so; do not inflate risk or manufacture findings.
+
+## Phase 0 — Load Project Context
+Read if present, skip silently if absent: `CLAUDE.md` or `AGENTS.md` (auth mechanism, known constraints); `docs/architecture/auth-and-sessions.md` (auth flow); `.claude/settings.json` (permissions, hooks, MCP servers); Codex `config.toml` if present.
+Use it to learn the intended permission model and auth flow so a deviation becomes a finding. Violations of DOCUMENTED conventions → report with HIGH confidence.
+
+## Evidence Gate
+Report a finding ONLY if all four hold:
+1. **Citation** — exact `file:line` you Read in this session, never from memory.
+2. **Failure mode** — a concrete input/path that triggers the exploit (no "could be problematic").
+3. **Context** — you read the surrounding hook/agent/settings block, not just the flagged line.
+4. **Severity** you can defend to a skeptic.
+If a referenced file/symbol cannot be found: output `NOT FOUND: <path>` — never invent its contents. A clean review (0 findings) is a valid result — do not manufacture findings.
+
+## Severity / Confidence
+Severity — CRITICAL: data loss, security, crash · WARNING: incorrect behavior under specific conditions, perf degradation · SUGGESTION: style/readability, safe to ignore.
+Confidence — HIGH (≥80): exploit visible in the code · MEDIUM (60–79): pattern-based, mark "needs verification" · LOW (<60): route to Open Questions, never silently drop.
+SAST mapping — a printed `[CRITICAL]`→CRITICAL, `[HIGH]`→WARNING, `[MEDIUM]`→SUGGESTION.
+
+## Phase 1 — Red Team (Attacker Perspective)
+Goal: enumerate exploits. Think like a malicious actor. List every file under `.claude/` (settings.json, each hook, each agent/command prompt, MCP config) plus CLAUDE.md / AGENTS.md, and Read each before flagging it.
+Attack vectors to explore:
+- Command injection through hook scripts (unquoted `$VAR`, `eval`, backticks).
+- Data exfiltration (env vars, source, credentials) via hooks or MCP servers.
+- Wildcard permission abuse for filesystem/command access (`Bash(*)`, broad globs).
+- Chained findings (e.g., hook injection + Bash wildcard = RCE).
+- Safety-check bypass (block-dangerous-git) via encoding or quoting tricks.
+- Prompt injection into agent prompts via CLAUDE.md / agent-file manipulation.
+For each finding record: attack vector; concrete triggering input; blast radius (single file / full system / network); how it is exploited in practice; whether it chains.
+Done-when: every `.claude/` file enumerated and Read; each finding has a `file:line` citation and a concrete exploit input.
+
+## Phase 2 — Blue Team (Defender Perspective)
+Goal: assess defenses. For each Red finding: existing protection in place; gap between current and secure state; specific hardening measure; priority by effort vs impact (quick wins first).
+Defense categories: input validation in hooks; permission scoping (replace wildcards with specific patterns); MCP server sandboxing; agent prompt integrity; monitoring / alerting.
+Done-when: every Red finding has exactly one Blue row.
+
+## Phase 3 — Static SAST Scan
+Goal: add pattern-based evidence. Locate the scanner without hardcoding a repo path:
+1. Glob `**/red-blue-auditor/scan.sh`.
+2. Found → run: `bash <path> --path=<scan-root> --exit-on-critical`
+   (the `--path=` equals form is required; `--exit-on-critical` makes CRITICAL patterns exit 2.)
+3. Not found → record "SAST SKIPPED — scan.sh NOT FOUND", continue LLM-only; never invent scanner output.
+Interpret the exit code (only when found and run):
+- 0 → clean, no pattern hits.
+- 1 → non-critical findings (HIGH/MEDIUM) present.
+- 2 → CRITICAL patterns present → mark the repo **DO NOT MERGE** until resolved.
+- 3 → patterns dir missing → treat as SAST SKIPPED and note the error.
+Fold each printed `[CRITICAL|HIGH|MEDIUM]` line into the finding set via the SAST mapping.
+Done-when: scan ran and its exit code was interpreted, OR NOT FOUND was recorded.
+
+## Phase 4 — Auditor (Synthesis)
+Goal: combine Red + Blue + SAST into the Output Contract and compute the Risk Score:
+- Start at 100.
+- −20 per CRITICAL finding (LLM or SAST-CRITICAL).
+- −10 per WARNING finding (LLM or SAST-HIGH).
+- −15 per distinct attack chain.
+- +5 per verified existing mitigation.
+- Clamp the result to 0–100 (never below 0, never above 100).
+Do not inflate risk to seem thorough.
+Done-when: every Output Contract section is filled and the score is computed by this formula.
+
+## Output Contract
+Emit exactly these sections, in this order. Example values shown are illustrative:
+
+```markdown
+## Security Audit — <scan-root>
+
+### Findings
+[CRITICAL/HIGH] .claude/hooks/notify.sh:12 — unquoted $FILE runs attacker-controlled path as a command
+  Evidence: `bash -c $FILE` with no quoting; FILE comes from the tool input
+  Fix: quote the variable and validate against an allowlist
+
+### Attack Chains (most dangerous first)
+[Chain 1]: hook injection (.claude/hooks/notify.sh:12) + Bash(*) permission = Remote Code Execution
+  Step 1: attacker-controlled file path reaches the hook
+  Step 2: hook evaluates it as a command via unquoted $FILE
+  Step 3: Bash(*) permission executes the injected command
+  Impact: full system access
+  Fix: quote all variables in hooks + restrict Bash to specific commands
+
+### Defense Matrix
+| Finding | Current Protection | Gap | Fix | Effort |
+|---------|-------------------|-----|-----|--------|
+| Hook injection (.claude/hooks/notify.sh:12) | None | Critical | Quote variables, validate input | Low |
+
+### SAST Findings
+Command: bash <path> --path=<scan-root> --exit-on-critical
+Exit code: 2 → DO NOT MERGE    (or: SAST SKIPPED — scan.sh NOT FOUND)
+CRITICAL: 1 · HIGH: 0 · MEDIUM: 2
+[CRITICAL] secrets: hardcoded token — .claude/settings.json:8
+
+### Recommendations (prioritized)
+1. [CRITICAL] Quote all hook variables — fix immediately
+2. [WARNING] Scope Bash permission to named commands — fix this sprint
+
+### Risk Score: 35/100
+100 − 40 (2 CRITICAL: 1 LLM + 1 SAST) − 10 (1 WARNING) − 15 (1 chain) = 35. Clamped to 0–100.
+
+### Open Questions
+- .claude/hooks/deploy.sh:30 — suspected env leak into an MCP server; needs the MCP server config to confirm.
+```
+
+Secure config: emit `### Findings\nNone — configuration is secure.` and `### Risk Score: 100/100`. Do not manufacture findings.
+
+## Recap — non-negotiables
+- Scope = agent-runtime config only (`.claude/`, hooks, agent prompts, CLAUDE.md, Codex config) — not app source.
+- Evidence Gate: every finding = `file:line` Read this session + a concrete exploit input; else drop or Open Questions.
+- SAST: `bash <path> --path=<root> --exit-on-critical`; exit 2 = DO NOT MERGE; scan.sh missing = "SAST SKIPPED — NOT FOUND", never fabricate output.
+- Canonical enums CRITICAL/WARNING/SUGGESTION + HIGH/MEDIUM/LOW; Risk Score starts 100, apply deltas, clamp 0–100.
+- Report only after every phase (0–4) ran; a clean config is a valid result — do not inflate risk.

package/packages/extras/red-blue-auditor/patterns/agent-config.txt

@@ -0,0 +1,4 @@
+# Agent configuration anti-patterns
+HIGH|^allowed-tools:\s*\*\s*$|agent allowed-tools wildcard in frontmatter
+MEDIUM|^model:\s*haiku|agent using haiku (kit policy is all-Opus)
+MEDIUM|^model:\s*sonnet|agent using sonnet (kit policy is all-Opus)

package/packages/extras/red-blue-auditor/patterns/hook-injection.txt

@@ -0,0 +1,8 @@
+# Hook injection and RCE vectors
+CRITICAL|curl\s+[^|]*\|\s*sh|curl piped to shell
+CRITICAL|wget\s+[^|]*\|\s*(sh|bash)|wget piped to shell
+CRITICAL|bash -c "\$[A-Z_]+"|unquoted eval-equivalent
+CRITICAL|eval\s+"?\$\(|eval of command substitution
+HIGH|nc -e|netcat exec flag (reverse shell)
+HIGH|bash -i >&|interactive bash redirected (reverse shell)
+HIGH|echo\s+["'][a-zA-Z0-9+/=]{50,}["']\s*\|\s*base64 -d\s*\|\s*(sh|bash)|base64 decode piped to shell

package/packages/extras/red-blue-auditor/patterns/mcp-risk.txt

@@ -0,0 +1,5 @@
+# Risky MCP server configurations
+CRITICAL|"command"\s*:\s*"rm\s|MCP command executes rm
+CRITICAL|"command"\s*:\s*"curl\s|MCP command executes curl (supply chain risk)
+HIGH|"url"\s*:\s*"https?://[^"]*\..*"(?!.*allowlist)|remote MCP URL without allowlist context
+MEDIUM|"unsafe"\s*:\s*true|MCP unsafe flag

package/packages/extras/red-blue-auditor/patterns/permission-abuse.txt

@@ -0,0 +1,6 @@
+# Over-permissive .claude/settings.json patterns
+HIGH|"Bash\(\*\)"|Bash wildcard permission
+HIGH|"Write\(\*\)"|Write wildcard permission
+CRITICAL|"dangerouslyAllow[A-Za-z]+"\s*:\s*true|dangerouslyAllow flag set true
+CRITICAL|"dangerouslyDisable[A-Za-z]+"\s*:\s*true|dangerouslyDisable flag set true
+MEDIUM|"allowed-tools"\s*:\s*"\*"|agent allowed-tools wildcard

package/packages/extras/red-blue-auditor/patterns/secrets.txt

@@ -0,0 +1,17 @@
+# Secrets and API keys — CRITICAL findings
+CRITICAL|sk-[a-zA-Z0-9]{32,}|OpenAI API key
+CRITICAL|sk-ant-[a-zA-Z0-9-]{40,}|Anthropic API key
+CRITICAL|AKIA[0-9A-Z]{16}|AWS access key ID
+CRITICAL|aws_secret_access_key\s*=\s*['"][^'"]+['"]|AWS secret in quoted assignment
+CRITICAL|-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----|SSH/TLS private key
+CRITICAL|ghp_[a-zA-Z0-9]{36}|GitHub personal access token
+CRITICAL|gho_[a-zA-Z0-9]{36}|GitHub OAuth token
+CRITICAL|github_pat_[a-zA-Z0-9]{22}_[a-zA-Z0-9]{59}|GitHub fine-grained PAT
+CRITICAL|xox[abpr]-[a-zA-Z0-9-]{10,}|Slack token
+CRITICAL|[0-9]{9,10}:[a-zA-Z0-9_-]{35}|Telegram bot token
+CRITICAL|MTg[a-zA-Z0-9_-]{20,}\.[a-zA-Z0-9_-]{6}\.[a-zA-Z0-9_-]{27}|Discord bot token
+CRITICAL|sk_live_[a-zA-Z0-9]{24,}|Stripe live secret key
+CRITICAL|rk_live_[a-zA-Z0-9]{24,}|Stripe live restricted key
+CRITICAL|npm_[a-zA-Z0-9]{36}|npm token
+HIGH|AIzaSy[a-zA-Z0-9_-]{33}|Google API key
+HIGH|eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+|JWT token (unverified context)

package/packages/extras/red-blue-auditor/scan.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+# scan.sh — Bearer-style SAST scan against pattern files.
+# Usage: scan.sh [--exit-on-critical] [--patterns DIR] [--path PATH]
+# Exit codes: 0 clean, 1 any findings, 2 CRITICAL findings (with --exit-on-critical)
+
+set -u
+
+EXIT_ON_CRITICAL=0
+PATTERNS_DIR="$(dirname "$0")/patterns"
+SCAN_PATH="."
+
+for arg in "$@"; do
+  case "$arg" in
+    --exit-on-critical) EXIT_ON_CRITICAL=1 ;;
+    --patterns=*)       PATTERNS_DIR="${arg#--patterns=}" ;;
+    --path=*)           SCAN_PATH="${arg#--path=}" ;;
+    -h|--help)
+      echo "Usage: scan.sh [--exit-on-critical] [--patterns=DIR] [--path=PATH]"
+      echo ""
+      echo "Scans files under --path (default .) against all *.txt pattern files."
+      echo "Pattern file format per line: SEVERITY|REGEX|DESCRIPTION"
+      echo "Exit: 0 clean, 1 any finding, 2 CRITICAL finding (with --exit-on-critical)"
+      exit 0
+      ;;
+  esac
+done
+
+[ -d "$PATTERNS_DIR" ] || { echo "ERROR: patterns dir not found: $PATTERNS_DIR" >&2; exit 3; }
+
+crit=0
+high=0
+medium=0
+
+for pfile in "$PATTERNS_DIR"/*.txt; do
+  [ -f "$pfile" ] || continue
+  cat_name=$(basename "$pfile" .txt)
+
+  while IFS='|' read -r severity regex desc; do
+    # Skip comments and blanks
+    [ -z "${severity:-}" ] && continue
+    [[ "$severity" =~ ^[[:space:]]*# ]] && continue
+    [ -z "${regex:-}" ] && continue
+
+    # Trim whitespace
+    severity="$(echo "$severity" | tr -d '[:space:]')"
+
+    # grep with common exclusions
+    if HITS=$(grep -rEn "$regex" "$SCAN_PATH" \
+                --include="*.sh" --include="*.md" --include="*.json" \
+                --include="*.yml" --include="*.yaml" --include="*.go" \
+                --include="*.ts" --include="*.tsx" --include="*.js" \
+                --include="*.py" --include="*.rb" --include="*.rs" \
+                --include="*.env" --include=".env*" --include="*.ini" \
+                --include="*.toml" --include="*.txt" --include="*.conf" \
+                --exclude-dir=.git --exclude-dir=node_modules \
+                --exclude-dir=dist --exclude-dir=build \
+                --exclude-dir=.next --exclude-dir=target \
+                2>/dev/null); then
+      while IFS= read -r hit; do
+        [ -z "$hit" ] && continue
+        echo "[$severity] $cat_name: $desc"
+        echo "  $hit"
+        case "$severity" in
+          CRITICAL) crit=$((crit+1)) ;;
+          HIGH) high=$((high+1)) ;;
+          MEDIUM) medium=$((medium+1)) ;;
+        esac
+      done <<< "$HITS"
+    fi
+  done < "$pfile"
+done
+
+echo ""
+echo "═══════════════════════════════════════════"
+echo "AgentShield scan complete"
+echo "  CRITICAL: $crit"
+echo "  HIGH:     $high"
+echo "  MEDIUM:   $medium"
+echo "═══════════════════════════════════════════"
+
+if [ "$EXIT_ON_CRITICAL" = "1" ] && [ "$crit" -gt 0 ]; then
+  echo "CI gate: exiting 2 (CRITICAL findings blocked)" >&2
+  exit 2
+elif [ "$crit" -gt 0 ] || [ "$high" -gt 0 ] || [ "$medium" -gt 0 ]; then
+  exit 1
+fi
+
+exit 0