@sentry/warden 0.21.0 → 0.22.0

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}
+```