@sentry/warden 0.21.0 → 0.23.0

package/skills/warden-sweep/references/issue-phase.md

@@ -0,0 +1,24 @@
+# Issue Phase
+
+Create a tracking issue that ties all generated PRs together and gives reviewers one overview.
+
+## Run
+
+```bash
+uv run <skill-root>/scripts/create_issue.py ${SWEEP_DIR}
+```
+
+## Process
+
+1. Parse the JSON stdout.
+2. Save `issueUrl` and `issueNumber`.
+3. If the script fails, show the error and continue to the patch phase. PRs can still be created without a tracking issue.
+4. Update the checklist: Phase 3 complete.
+
+## Report Template
+
+```markdown
+## Tracking Issue Created
+
+{issueUrl}
+```

package/skills/warden-sweep/references/organize-phase.md

@@ -0,0 +1,31 @@
+# Organize Phase
+
+Finalize sweep artifacts, security views, PR links, and the summary report.
+
+## Run
+
+```bash
+uv run <skill-root>/scripts/organize.py ${SWEEP_DIR}
+```
+
+## Process
+
+1. Parse the JSON stdout.
+2. Confirm `summary.md` and `data/report.json` were produced.
+3. If the script fails, show the error and note which phases completed.
+4. Update the checklist: Phase 5 complete.
+
+## Report Template
+
+```markdown
+## Sweep Complete
+
+| Metric | Count |
+|--------|-------|
+| Files scanned | {filesScanned} |
+| Findings verified | {verified} |
+| PRs created | {prsCreated} |
+| Security findings | {securityFindings} |
+
+Full report: `{summaryPath}`
+```

package/skills/warden-sweep/references/patch-phase.md

@@ -0,0 +1,142 @@
+# Patch Phase
+
+Create isolated fixes for verified findings and open draft PRs.
+
+## Contents
+
+- Rules
+- Setup
+- Per-Finding Process
+- Dedup Check
+- Worktree, Fix, Reviewers, And PR
+- Report Template
+
+## Rules
+
+- Patch high-severity and above.
+- Patch medium findings only when they come from bug-detection skills such as `code-review` or `security-review`.
+- Skip low and info findings.
+- Process findings sequentially.
+- Create one worktree and one branch per finding.
+- Clean up worktrees after success or failure.
+
+## Setup
+
+Index existing PRs before patching:
+
+```bash
+uv run <skill-root>/scripts/index_prs.py ${SWEEP_DIR}
+```
+
+Parse the JSON stdout and use `fileIndex` for dedup checks.
+
+Determine the default branch and fetch latest:
+
+```bash
+DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
+git fetch origin "${DEFAULT_BRANCH}"
+```
+
+## Per-Finding Process
+
+For each finding in `data/verified.jsonl`:
+
+1. If the finding ID already exists in `data/patches.jsonl`, skip it.
+2. Run the dedup check.
+3. Create a worktree.
+4. Apply the fix using `references/patch-prompt.md`.
+5. If the patch task returns `"status": "skipped"`, record an error, clean up the worktree, and continue.
+6. Find reviewers.
+7. Push the branch.
+8. Create a draft PR.
+9. Record the result in `data/patches.jsonl`.
+10. Clean up the worktree.
+
+## Dedup Check
+
+Use the file index from `index_prs.py`:
+
+1. File match: if no open Warden PR touches the finding file, proceed.
+2. Chunk overlap: if a PR touches the same file, read `data/pr-diffs/<number>.diff` and check whether changed hunks overlap or sit within roughly 10 lines of the finding range.
+3. Same concern: compare PR title and finding title/description.
+
+Skip the finding only when there is both chunk overlap and the PR addresses the same concern. Record it with `"status": "existing"` and the matching `prUrl`.
+
+## Worktree, Fix, Reviewers, And PR
+
+```bash
+BRANCH="warden-sweep/${RUN_ID}/${FINDING_ID}"
+WORKTREE="${SWEEP_DIR}/worktrees/${FINDING_ID}"
+git worktree add "${WORKTREE}" -b "${BRANCH}" "origin/${DEFAULT_BRANCH}"
+```
+
+Each finding branches from the default branch so PRs contain only the fix commit.
+
+Run patch work using the host agent's task/delegation mechanism when available. Read `references/patch-prompt.md` and substitute the finding values and worktree path into the `${...}` placeholders.
+
+If delegated tasks are not available, apply the prompt instructions yourself in the worktree.
+
+```bash
+uv run <skill-root>/scripts/find_reviewers.py "${FILE_PATH}"
+```
+
+```bash
+cd "${WORKTREE}" && git push -u origin HEAD:"${BRANCH}"
+```
+
+Create the PR with a short "what" summary followed by the finding description and verification reasoning:
+
+```bash
+gh pr create --draft \
+  --label "warden" \
+  --title "fix: ${TITLE}" \
+  --body "$(cat <<'EOF'
+${FIX_WHAT_DESCRIPTION}
+
+${DESCRIPTION}
+
+${REASONING}
+
+Automated fix for Warden finding ${FINDING_ID} (${SEVERITY}, detected by ${SKILL}).
+
+<!-- Only include the next line if Phase 3 succeeded and ISSUE_NUMBER is available -->
+Ref #${ISSUE_NUMBER}
+
+> This PR was auto-generated by a Warden Sweep (run ${RUN_ID}).
+> The finding has been validated through automated deep tracing,
+> but human confirmation is requested as this is batch work.
+EOF
+)" ${REVIEWERS}
+```
+
+## Record Result
+
+Append to `data/patches.jsonl`. Use `"created"` for successful PRs, not the patch task's `"applied"` status.
+
+```json
+{"findingId": "...", "prUrl": "https://...", "branch": "...", "reviewers": ["user1", "user2"], "filesChanged": ["..."], "status": "created|existing|error"}
+```
+
+Clean up:
+
+```bash
+cd "$(git rev-parse --show-toplevel)"
+git worktree remove "${WORKTREE}" --force
+```
+
+On failure at any step, write `"status": "error"` with an `"error"` message, clean up the worktree, and continue.
+
+Update the manifest: set `phases.patch` to `"complete"`.
+
+## Report Template
+
+```markdown
+## PRs Created
+
+**{created}** created, **{skipped}** skipped (existing), **{failed}** failed.
+
+| # | Finding | PR | Status |
+|---|---------|----|--------|
+| 1 | `security-review-a1b2c3d4` SQL injection in query builder | #142 | created |
+| 2 | `code-review-e5f6g7h8` Null pointer in handler | - | existing (#138) |
+```

package/skills/warden-sweep/references/resume-and-artifacts.md

@@ -0,0 +1,51 @@
+# Resume And Artifacts
+
+Use this reference when resuming a partial sweep or inspecting generated files.
+
+## Resume Rules
+
+Each phase is incremental:
+
+1. Check `data/manifest.json` for phase state.
+2. For scan, pass `--sweep-dir` to `scan.py`.
+3. For verify, skip existing `data/verify/<id>.json` files.
+4. For issue, `create_issue.py` skips if `issueUrl` exists in the manifest.
+5. For patch, skip existing entries in `data/patches.jsonl`.
+6. For organize, rerun safely.
+
+Continue from the first incomplete phase. Do not start a new sweep unless the user asks for a clean run.
+
+## Output Directory Structure
+
+```text
+.warden/sweeps/<run-id>/
+  summary.md                        # Stats, key findings, PR links
+  findings/                         # One markdown per verified finding
+    <finding-id>.md
+  security/                         # Security-specific view
+    index.jsonl                     # Security findings index
+    <finding-id>.md                 # Copies of security findings
+  data/                             # Structured data for tooling
+    manifest.json                   # Run metadata, phase state
+    scan-index.jsonl                # Per-file scan tracking
+    all-findings.jsonl              # Every finding from scan
+    verified.jsonl                  # Findings that passed verification
+    rejected.jsonl                  # Findings that failed verification
+    patches.jsonl                   # Finding -> PR URL -> reviewers
+    existing-prs.json               # Cached open Warden PRs
+    report.json                     # Machine-readable summary
+    verify/                         # Individual verification results
+      <finding-id>.json
+    logs/                           # Warden JSONL logs per file
+      <hash>.jsonl
+    pr-diffs/                       # Cached PR diffs for dedup
+      <number>.diff
+```
+
+## Failure Handling
+
+- Preserve partial artifacts.
+- Record per-finding errors in the relevant JSONL file.
+- Distinguish timed-out files from errored files.
+- Clean up worktrees before retrying patch work.
+- Re-run organize after manual recovery to refresh reports.

package/skills/warden-sweep/references/scan-phase.md

@@ -0,0 +1,46 @@
+# Scan Phase
+
+Run Warden across repository files and collect normalized findings.
+
+## Run
+
+```bash
+uv run <skill-root>/scripts/scan.py
+```
+
+To scan only specific files:
+
+```bash
+uv run <skill-root>/scripts/scan.py src/foo.ts src/bar.ts
+```
+
+To resume a partial scan:
+
+```bash
+uv run <skill-root>/scripts/scan.py --sweep-dir .warden/sweeps/<run-id>
+```
+
+## Process
+
+1. Parse the JSON stdout.
+2. Save `runId` and `sweepDir`.
+3. Treat exit code `1` as fatal and stop.
+4. Treat exit code `2` as partial: report timed-out and errored files separately, then continue only if the user accepts the partial results.
+5. Render every finding from the `findings` array.
+6. Update the checklist: Phase 1 complete.
+
+## Report Template
+
+```markdown
+## Scan Complete
+
+Scanned **{filesScanned}** files, **{filesTimedOut}** timed out, **{filesErrored}** errors.
+
+### Findings ({totalFindings} total)
+
+| # | Severity | Skill | File | Title |
+|---|----------|-------|------|-------|
+| 1 | **HIGH** | security-review | `src/db/query.ts:42` | SQL injection in query builder |
+```
+
+Bold severity for high and above.

package/skills/warden-sweep/references/script-interfaces.md

@@ -0,0 +1,127 @@
+# Script Interfaces
+
+Use this reference before running Warden Sweep scripts. Run scripts from the repository root and pass the host skill-root path.
+
+## Contents
+
+- `scan.py`
+- `index_prs.py`
+- `create_issue.py`
+- `organize.py`
+- `extract_findings.py`
+- `generate_report.py`
+- `find_reviewers.py`
+
+## `scripts/scan.py`
+
+Runs setup and scan in one call: generates a run ID, creates the sweep directory, checks dependencies, creates the `warden` label, enumerates files, runs Warden per file, writes `scan-index.jsonl`, and extracts findings.
+
+```bash
+uv run <skill-root>/scripts/scan.py [file ...]
+uv run <skill-root>/scripts/scan.py --sweep-dir .warden/sweeps/<run-id>
+```
+
+Stdout JSON:
+
+```json
+{
+  "runId": "abc123",
+  "sweepDir": ".warden/sweeps/abc123",
+  "filesScanned": 10,
+  "filesTimedOut": 0,
+  "filesErrored": 0,
+  "totalFindings": 3,
+  "findings": []
+}
+```
+
+Exit codes: `0` success, `1` fatal error, `2` partial scan.
+
+## `scripts/index_prs.py`
+
+Fetches open Warden-labeled PRs, builds a file-to-PR dedup index, and caches diffs for overlapping PRs.
+
+```bash
+uv run <skill-root>/scripts/index_prs.py <sweep-dir>
+```
+
+Stdout JSON includes `fileIndex`. Side effects:
+
+- writes `data/existing-prs.json`
+- writes `data/pr-diffs/<number>.diff` for overlapping PRs
+
+## `scripts/create_issue.py`
+
+Creates a GitHub tracking issue summarizing verified sweep results.
+
+```bash
+uv run <skill-root>/scripts/create_issue.py <sweep-dir>
+```
+
+Stdout JSON:
+
+```json
+{
+  "issueUrl": "https://github.com/owner/repo/issues/123",
+  "issueNumber": 123
+}
+```
+
+Idempotent: skips creation when `issueUrl` already exists in the manifest.
+
+## `scripts/organize.py`
+
+Tags security findings, labels security PRs, updates finding reports with PR links, posts final results to the tracking issue, generates the summary report, and finalizes the manifest.
+
+```bash
+uv run <skill-root>/scripts/organize.py <sweep-dir>
+```
+
+Stdout JSON includes final sweep counts and report paths. Side effects:
+
+- creates `security/index.jsonl`
+- copies security finding reports to `security/`
+- creates or reuses the `security` GitHub label
+- labels security PRs
+- appends PR links to `findings/*.md`
+- writes `summary.md` and `data/report.json`
+- updates `phases.organize` in `data/manifest.json`
+
+## `scripts/extract_findings.py`
+
+Parses Warden JSONL log files and extracts normalized findings. Usually called by `scan.py`.
+
+```bash
+uv run <skill-root>/scripts/extract_findings.py <log-path-or-directory> -o <output.jsonl>
+```
+
+Writes one normalized finding per line to `<output.jsonl>`.
+
+## `scripts/generate_report.py`
+
+Builds `summary.md` and `report.json` from sweep data. Usually called by `organize.py`.
+
+```bash
+uv run <skill-root>/scripts/generate_report.py <sweep-dir>
+```
+
+Side effects:
+
+- writes `<sweep-dir>/summary.md`
+- writes `<sweep-dir>/data/report.json`
+
+## `scripts/find_reviewers.py`
+
+Finds the top two git contributors for a file from the last 12 months.
+
+```bash
+uv run <skill-root>/scripts/find_reviewers.py <file-path>
+```
+
+Stdout JSON:
+
+```json
+{
+  "reviewers": ["user1", "user2"]
+}
+```

package/skills/warden-sweep/references/verify-phase.md

@@ -0,0 +1,69 @@
+# Verify Phase
+
+Deep-trace every finding before patching. This phase qualifies true issues and rejects false positives.
+
+## Input
+
+Read findings from:
+
+```text
+<sweep-dir>/data/all-findings.jsonl
+```
+
+## Process
+
+For each finding:
+
+1. If `data/verify/<finding-id>.json` exists, skip it.
+2. Launch verification work using the host agent's task/delegation mechanism when available. Process findings in parallel batches up to 8 if the host supports parallel work.
+3. Read `references/verify-prompt.md` and substitute the finding values into the `${...}` placeholders.
+4. Parse the returned JSON.
+5. Write the raw result to `data/verify/<finding-id>.json`.
+6. Append verified findings to `data/verified.jsonl`.
+7. Append rejected findings to `data/rejected.jsonl`.
+8. For verified findings, generate `findings/<finding-id>.md`.
+
+If the host does not support delegated tasks, run the same verification prompt serially.
+
+## Verified Finding Report
+
+````markdown
+# ${TITLE}
+
+**ID**: ${FINDING_ID} | **Severity**: ${SEVERITY} | **Confidence**: ${CONFIDENCE}
+**Skill**: ${SKILL} | **File**: ${FILE_PATH}:${START_LINE}
+
+## Description
+${DESCRIPTION}
+
+## Verification
+**Verdict**: Verified (${VERIFICATION_CONFIDENCE})
+**Reasoning**: ${REASONING}
+**Code trace**: ${TRACE_NOTES}
+
+## Suggested Fix
+${FIX_DESCRIPTION}
+```diff
+${FIX_DIFF}
+```
+````
+
+Update the manifest: set `phases.verify` to `"complete"`.
+
+## Report Template
+
+```markdown
+## Verification Complete
+
+**{verified}** verified, **{rejected}** rejected.
+
+### Verified Findings
+
+| # | Severity | Confidence | File | Title | Reasoning |
+|---|----------|------------|------|-------|-----------|
+| 1 | **HIGH** | high | `src/db/query.ts:42` | SQL injection in query builder | User input flows directly into... |
+
+### Rejected ({rejected_count})
+
+- `{findingId}` {file}: {reasoning}
+```

package/src/builtin-skills/security-review/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: security-review
+description: Finds exploitable application security vulnerabilities in code changes. Use for Warden security scans, appsec review, OWASP-style checks, authentication or authorization bugs, injection, XSS, SSRF, path traversal, secrets, unsafe crypto, webhook verification, open redirects, or sensitive data exposure.
+allowed-tools: Read Grep Glob
+---
+
+You are a senior application security reviewer finding real, exploitable vulnerabilities in code changes for Warden's broad default security skill.
+Keep the review simple and high-signal: trace source, boundary, sink, mitigation, and impact before reporting.
+
+## References
+
+Load only matching references:
+
+| Reference | Read When |
+|-----------|-----------|
+| `references/javascript-typescript.md` | Reviewing JavaScript, TypeScript, Node, React, Next.js, or browser code |
+| `references/python.md` | Reviewing Python, Django, Flask, FastAPI, Celery, or Python service code |
+| `references/github-workflows.md` | Reviewing GitHub Actions workflows, local actions, reusable workflows, or workflow-loaded scripts/config |
+
+## Finding Requirements
+
+- Report a finding only when you can show attacker-controlled input, the vulnerable sink or missing guard, the security boundary, and concrete impact.
+- Identify attacker-controlled input: request bodies, query strings, path params, cookies, headers, uploads, webhooks, OAuth callbacks, third-party callbacks, user-written database values, and caller-controlled service inputs.
+- Identify the security boundary: login state, session, tenant, org, team, account, project, role, webhook signature, internal network, filesystem root, cache namespace, or paid quota.
+- Follow imports, wrappers, middleware, validators, serializers, auth helpers, route definitions, shared utilities, sibling handlers, and framework conventions before reporting.
+- Verify mitigations in the effective path. Parameterized queries, exact allowlists, safe URL fetchers, escaping, signature checks, handler-level auth, ownership checks, realpath containment, and quota controls can close the path.
+- Treat pattern matches as leads. A dangerous API is not a vulnerability unless untrusted data can reach it without an effective mitigation.
+- Prefer no finding over speculative hardening advice.
+
+## Investigation Process
+
+1. Read the changed hunk and target file enough to understand the effective execution path.
+2. Confirm the code is production-reachable. Return no findings for generated, vendored, test-only, fixture, example, migration, or build-output code unless it is actually shipped or invoked.
+3. Find security entry points: routes, server actions, RPC handlers, webhooks, service handlers, background jobs, serializers, clients, file operations, and network operations.
+4. Trace suspicious values from source to sink or missing guard.
+5. Read imported guards, validators, auth wrappers, schemas, middleware, shared utilities, and sibling handlers when they decide exploitability.
+6. Check whether mitigations block the real path, not just a nearby path.
+7. Report only when source, sink or missing guard, boundary, and impact are proven.
+
+## What To Report
+
+| Category | Report When |
+|----------|-------------|
+| Authentication | Login, session, token, OAuth, SSO, reset, webhook, or service identity checks can be bypassed, spoofed, replayed, or confused. |
+| Authorization | Tenant, org, team, account, project, role, owner, or resource checks are missing, inverted, stale, or performed on the wrong actor. |
+| Injection and RCE | User input reaches SQL/NoSQL, shell, template, eval, deserialization, expression, or dynamic import sinks without parameterization or allowlisting. |
+| XSS and unsafe HTML | User-controlled data reaches HTML, DOM, script, Markdown HTML, unsafe URLs, or framework escape hatches without context-correct escaping or sanitization. |
+| SSRF and redirects | User-controlled URLs, hosts, redirects, callbacks, proxies, or fetchers can reach internal services, metadata endpoints, or trusted redirect flows. |
+| Filesystem and uploads | User-controlled paths, archive entries, object keys, filenames, or uploads can escape an intended root, overwrite sensitive files, or become executable. |
+| Secrets and data exposure | Real credentials, tokens, private keys, signed URLs, auth headers, cookies, PII, stack traces, or internal fields are exposed to untrusted users, clients, or logs. |
+| Crypto and randomness | Weak hashes, predictable random values, static IVs, ECB mode, timing-unsafe compares, unsigned tokens, or custom crypto protect security-sensitive data. |
+| Abuse controls | Sensitive or expensive operations such as login, MFA, invites, exports, password reset, billing, email, SMS, or paid API calls lack meaningful rate, quota, replay, or idempotency controls. |
+| CI and workflows | Workflow changes let untrusted or caller-controlled code, text, artifacts, caches, or actions reach privileged execution, secrets, write tokens, releases, packages, deployments, or sensitive runners. |
+
+## Severity
+
+| Level | Use For |
+|-------|---------|
+| high | Broad auth bypass, privilege escalation, cross-tenant sensitive data access, RCE, SQL/NoSQL injection over sensitive data, SSRF to internal services or cloud metadata, unsafe deserialization, production credential exposure, privileged CI execution, or destructive unauthorized actions. |
+| medium | XSS with script execution, bounded path traversal, sensitive information disclosure, webhook side effects without verification, open redirects in auth/token flows, weak token validation, meaningful abuse of expensive or sensitive operations, or limited unauthorized data mutation. |
+| low | Concrete defense-in-depth flaw with a plausible exploit path and limited impact. Do not use low for vague best-practice advice. |
+
+- Tie-breaker: choose the lower severity when impact depends on unproven preconditions.
+
+## What Not To Report
+
+- Code fully mitigated by a verified guard in the effective path.
+- Sinks fed only by constants, trusted server-side values, test data, migrations, generated code, vendored code, examples, or build output.
+- Generic dependency CVEs unless the changed code makes the vulnerable behavior reachable.
+- Style, lint, maintainability, performance, missing comments, or generic best-practice recommendations.
+- Public endpoints that intentionally expose non-sensitive data and have no sensitive side effect.
+- Workflow style, actionlint issues, broad permissions, or mutable action refs without a traced path to execution, credential exposure, trusted artifacts, or privileged side effects.
+- Secret-looking placeholders such as `example`, `test`, `dummy`, documented fake keys, or values confined to tests.
+- Framework defaults that already escape, parameterize, validate, or authorize unless the code uses an unsafe escape hatch.
+
+## Finding Format
+
+- Title: name the vulnerability and impact.
+- Description: include source, sink or missing guard, boundary crossed, and attacker-visible consequence.
+- `verification`: list checked files, functions, guards, or sibling paths.
+- `suggestedFix`: include only when the fix is complete for the analyzed file.

package/src/builtin-skills/security-review/SPEC.md

@@ -0,0 +1,77 @@
+# Security Review Skill Specification
+
+## Intent
+
+The `security-review` skill is Warden's broad default application security scanner. It gives teams a usable first-pass security review without importing benchmark prompts or requiring language-specific setup.
+
+It should catch common exploitable vulnerabilities in changed production code while avoiding noisy hardening advice.
+
+## Scope
+
+In scope:
+
+- Authentication, authorization, tenant isolation, identity, and service-boundary bugs.
+- Injection, RCE, unsafe deserialization, XSS, SSRF, path traversal, unsafe redirects, webhook verification, secrets exposure, weak crypto, sensitive data exposure, and meaningful abuse-control gaps.
+- General guidance that applies across web services and application code.
+- Focused notes for JavaScript/TypeScript, Python, and GitHub Actions workflows.
+
+Out of scope:
+
+- Full dependency CVE triage without reachable changed code.
+- Compliance checklists, infrastructure-only policy review, or exhaustive cloud IAM audits.
+- Style, maintainability, performance, or non-security correctness bugs.
+- Benchmark-specific prompt compatibility.
+- Large language-specific catalogs in `SKILL.md`.
+
+## Users And Trigger Context
+
+- Primary users: coding agents and Warden runs reviewing pull requests or local changes.
+- Should trigger for: "security review", "scan for vulnerabilities", "appsec review", "OWASP check", "auth bypass", "XSS", "SQL injection", "SSRF", "path traversal", "secret exposure", or equivalent security-focused review requests.
+- Should not trigger for: generic code review, prompt-writing help, Warden CLI usage, or broad architecture review with no security focus.
+
+## Runtime Contract
+
+- Required first actions:
+  - Identify whether changed files are production code or test/generated/vendor/example code.
+  - Read the target file and any guards, helpers, middleware, validators, serializers, or sibling handlers needed to prove the path.
+  - Load only the matching language reference when it materially improves the review.
+- Required finding evidence:
+  - attacker-controlled source
+  - vulnerable sink or missing guard
+  - crossed security boundary
+  - concrete attacker-visible impact
+  - verification details naming checked files/functions
+- Required outputs:
+  - Warden findings only for high-confidence vulnerabilities.
+  - Empty findings when exploitability is not proven.
+- Non-negotiable constraints:
+  - Do not report pattern-only suspicions.
+  - Do not lower the bar to create coverage.
+  - Do not add language-specific examples to `SKILL.md`; route them to `references/`.
+
+## Reference Architecture
+
+- `SKILL.md` contains the broad review contract, category table, severity rubric, exclusions, and reference routing.
+- `references/javascript-typescript.md` contains JS/TS/Node/React/Next-specific examples and false-positive controls.
+- `references/python.md` contains Python/Django/Flask/FastAPI-specific examples and false-positive controls.
+- `references/github-workflows.md` contains GitHub Actions workflow examples and false-positive controls.
+- `scripts/`, `assets/`, and `references/evidence/` are unused until repeated evidence warrants them.
+
+## Evaluation
+
+- Lightweight validation:
+  - Run the skill validator against `src/builtin-skills/security-review`.
+  - Verify every reference is directly routed from `SKILL.md`.
+  - Run init command tests that install bundled skills.
+- Deeper evaluation:
+  - Add eval cases for SQL injection, XSS, SSRF, authz bypass, secrets, and safe counterexamples.
+  - Compare false positives against sanitized real Warden runs.
+- Acceptance gates:
+  - `SKILL.md` stays concise enough to scan.
+  - Language-specific examples stay in references.
+  - Findings require exploitability evidence, not keyword matches.
+
+## Maintenance Notes
+
+- Add a new language reference only when recurring findings need language-specific calibration.
+- Keep examples minimal and transformed; do not store proprietary code.