@sentry/warden 0.21.0 → 0.22.0

package/skills/warden/references/config-schema.md

@@ -1,5 +1,14 @@
 # warden.toml Configuration Schema
 
+## Contents
+
+- Top-Level Structure
+- Defaults Section
+- Skills Section
+- Severity Values
+- Built-in Skip Patterns
+- Environment Variables
+
 ## Top-Level Structure
 
 ```toml

package/skills/warden/references/configuration.md

@@ -1,5 +1,14 @@
 # Configuration (warden.toml)
 
+## Contents
+
+- Minimal Example
+- Skill Configuration
+- Common Patterns
+- Model Precedence
+- Environment Variables
+- Troubleshooting
+
 See [config-schema.md](config-schema.md) for the complete schema reference.
 
 ## Minimal Example

package/skills/warden-sweep/SKILL.md

@@ -1,350 +1,70 @@
 ---
 name: warden-sweep
-description: Full-repository code sweep. Scans every file with warden, verifies findings via deep tracing, creates draft PRs for validated issues. Use when asked to "sweep the repo", "scan everything", "find all bugs", "full codebase review", "batch code analysis", or run warden across the entire repository.
+description: Full-repository code sweep. Scans every file with Warden, verifies findings through deep tracing, creates draft PRs for validated issues. Use when asked to "sweep the repo", "scan everything", "find all bugs", "full codebase review", "batch code analysis", or run Warden across the entire repository.
 disable-model-invocation: true
 ---
 
 # Warden Sweep
 
-Full-repository code sweep: scan every file, verify findings with deep tracing, create draft PRs for validated issues.
+Run a full-repository Warden sweep: scan files, verify findings, create a tracking issue, open draft PRs for validated issues, and organize the final report.
 
-**Requires**: `warden`, `gh`, `git`, `jq`, `uv`
+**Requires**: `warden`, `gh`, `git`, `jq`, `uv`.
 
-**Important**: Run all scripts from the repository root using `${CLAUDE_SKILL_ROOT}`. Output goes to `.warden/sweeps/<run-id>/`.
+Run commands from the repository root. Use the host's skill-root path for bundled scripts and references.
 
-## Bundled Scripts
+Output goes to `.warden/sweeps/<run-id>/`.
 
-### `scripts/scan.py`
+## References
 
-Runs setup and scan in one call: generates run ID, creates sweep dir, checks deps, creates `warden` label, enumerates files, runs warden per file, extracts findings.
+Load only the reference for the current phase:
 
-```bash
-uv run ${CLAUDE_SKILL_ROOT}/scripts/scan.py [file ...]
-  --sweep-dir DIR     # Resume into existing sweep dir
-```
-
-### `scripts/index_prs.py`
-
-Fetches open warden-labeled PRs, builds file-to-PR dedup index, caches diffs for overlapping PRs.
-
-```bash
-uv run ${CLAUDE_SKILL_ROOT}/scripts/index_prs.py <sweep-dir>
-```
-
-### `scripts/create_issue.py`
-
-Creates a GitHub tracking issue summarizing sweep results. Run after verification, before patching.
-
-```bash
-uv run ${CLAUDE_SKILL_ROOT}/scripts/create_issue.py <sweep-dir>
-```
-
-### `scripts/organize.py`
-
-Tags security findings, labels security PRs, updates finding reports with PR links, posts final results to tracking issue, generates summary report, finalizes manifest.
-
-```bash
-uv run ${CLAUDE_SKILL_ROOT}/scripts/organize.py <sweep-dir>
-```
-
-### `scripts/extract_findings.py`
-
-Parses warden JSONL log files and extracts normalized findings. Called automatically by `scan.py`.
-
-```bash
-uv run ${CLAUDE_SKILL_ROOT}/scripts/extract_findings.py <log-path-or-directory> -o <output.jsonl>
-```
-
-### `scripts/generate_report.py`
-
-Builds `summary.md` and `report.json` from sweep data. Called automatically by `organize.py`.
-
-```bash
-uv run ${CLAUDE_SKILL_ROOT}/scripts/generate_report.py <sweep-dir>
-```
-
-### `scripts/find_reviewers.py`
-
-Finds top 2 git contributors for a file (last 12 months).
-
-```bash
-uv run ${CLAUDE_SKILL_ROOT}/scripts/find_reviewers.py <file-path>
-```
-
-Returns JSON: `{"reviewers": ["user1", "user2"]}`
-
----
-
-## Phase 1: Scan
-
-**Run** (1 tool call):
-
-```bash
-uv run ${CLAUDE_SKILL_ROOT}/scripts/scan.py
-```
-
-To resume a partial scan:
-
-```bash
-uv run ${CLAUDE_SKILL_ROOT}/scripts/scan.py --sweep-dir .warden/sweeps/<run-id>
-```
-
-Parse the JSON stdout. Save `runId` and `sweepDir` for subsequent phases.
-
-**Report** to user:
-
-```
-## 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 |
-...
-```
+| Need | Read |
+|------|------|
+| Script arguments, outputs, and side effects | `references/script-interfaces.md` |
+| Phase 1 scan workflow | `references/scan-phase.md` |
+| Phase 2 verification workflow | `references/verify-phase.md` |
+| Phase 3 tracking issue workflow | `references/issue-phase.md` |
+| Phase 4 patch and draft PR workflow | `references/patch-phase.md` |
+| Phase 5 organize and final report workflow | `references/organize-phase.md` |
+| Resume behavior and artifact layout | `references/resume-and-artifacts.md` |
+| Verification task prompt template | `references/verify-prompt.md` |
+| Patch task prompt template | `references/patch-prompt.md` |
 
-Render every finding from the `findings` array. Bold severity for high and above.
+## Workflow
 
-**On failure**: If exit code 1, show the error JSON and stop. If exit code 2, show the partial results. List timed-out files separately from errored files so users know which can be retried.
+Track progress across phases:
 
----
-
-## Phase 2: Verify
-
-Deep-trace each finding using Task subagents to qualify or disqualify.
+- [ ] Phase 1: Scan repository files with Warden.
+- [ ] Phase 2: Verify findings before patching.
+- [ ] Phase 3: Create a tracking issue.
+- [ ] Phase 4: Patch verified findings and open draft PRs.
+- [ ] Phase 5: Organize results and produce the final report.
 
-**For each finding in `data/all-findings.jsonl`:**
+## Phase Order
 
-Check if `data/verify/<finding-id>.json` already exists (incrementality). If it does, skip.
+1. Read `references/script-interfaces.md` once before running scripts.
+2. Run Phase 1 from `references/scan-phase.md`. Save `runId` and `sweepDir`.
+3. Run Phase 2 from `references/verify-phase.md`. Verify every finding before patching.
+4. Run Phase 3 from `references/issue-phase.md`. Continue if issue creation fails.
+5. Run Phase 4 from `references/patch-phase.md`. Patch sequentially, one finding at a time.
+6. Run Phase 5 from `references/organize-phase.md`.
+7. For interrupted or partial runs, read `references/resume-and-artifacts.md` and continue from the first incomplete phase.
 
-Launch a Task subagent (`subagent_type: "general-purpose"`) for each finding. Process findings in parallel batches of up to 8 to improve throughput.
+## Non-Negotiable Rules
 
-**Task prompt for each finding:**
+- Verify findings before creating fixes.
+- Use draft PRs for generated patches.
+- Branch every patch from the repository default branch.
+- Patch findings sequentially; do not run patch workers in parallel.
+- Skip existing entries in sweep artifacts instead of duplicating work.
+- Record failures in sweep data and continue to the next finding when possible.
+- Clean up each worktree after patch success or failure.
 
-Read `${CLAUDE_SKILL_ROOT}/references/verify-prompt.md` for the prompt template. Substitute the finding's values into the `${...}` placeholders.
+## Final Response
 
-**Process results:**
-
-Parse the JSON from the subagent response and:
-- Write result to `data/verify/<finding-id>.json`
-- Append to `data/verified.jsonl` or `data/rejected.jsonl`
-- For verified findings, generate `findings/<finding-id>.md`:
+After organizing, 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 manifest: set `phases.verify` to `"complete"`.
-
-**Report** to user after all verifications:
-
-```
-## 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}
-...
-```
-
----
-
-## Phase 3: Issue
-
-Create a tracking issue that ties all PRs together and gives reviewers a single overview.
-
-**Run** (1 tool call):
-
-```bash
-uv run ${CLAUDE_SKILL_ROOT}/scripts/create_issue.py ${SWEEP_DIR}
-```
-
-Parse the JSON stdout. Save `issueUrl` and `issueNumber` for Phase 4.
-
-**Report** to user:
-
-```
-## Tracking Issue Created
-
-{issueUrl}
-```
-
-**On failure**: Show the error. Continue to Phase 4 (PRs can still be created without a tracking issue).
-
----
-
-## Phase 4: Patch
-
-For each verified finding, create a worktree, fix the code, and open a draft PR. Process findings **sequentially** (one at a time) since parallel subagents cross-contaminate worktrees.
-
-**Severity triage**: Patch HIGH and above. For MEDIUM, only patch findings from bug-detection skills (e.g., `code-review`, `security-review`). Skip LOW and INFO findings.
-
-**Step 0: Setup** (run once before the loop):
-
-```bash
-uv run ${CLAUDE_SKILL_ROOT}/scripts/index_prs.py ${SWEEP_DIR}
-```
-
-Parse the JSON stdout. Use `fileIndex` for dedup checks.
-
-Determine the default branch and fetch latest so worktrees branch from current upstream:
-
-```bash
-DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
-git fetch origin "${DEFAULT_BRANCH}"
-```
-
-**For each finding in `data/verified.jsonl`:**
-
-Check if finding ID already exists in `data/patches.jsonl` (incrementality). If it does, skip.
-
-**Dedup check**: Use the file index from `index_prs.py` output to determine if an existing open PR already addresses the same issue.
-
-1. **File match**: Look up the finding's file path in the `fileIndex`. If no PR touches that file, no conflict; proceed to Step 1.
-2. **Chunk overlap**: If a PR does touch the same file, read its cached diff from `data/pr-diffs/<number>.diff` and check whether the PR's changed hunks overlap with the finding's line range (startLine-endLine). Overlapping or adjacent hunks (within ~10 lines) indicate the same code region.
-3. **Same concern**: If the hunks overlap, compare the PR title and the finding title/description. Are they fixing the same kind of defect? A PR fixing an off-by-one error and a finding about a null check in the same function are different issues; both should proceed.
-
-Skip the finding only when there is both chunk overlap AND the PR addresses the same concern. Record it in `data/patches.jsonl` with `"status": "existing"` and `"prUrl"` pointing to the matching PR, then continue to the next finding.
-
-**Step 1: Create worktree**
-
-```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 repo's default branch so PRs contain only the fix commit.
-
-**Step 2: Generate fix**
-
-Launch a Task subagent (`subagent_type: "general-purpose"`) to apply the fix in the worktree. Read `${CLAUDE_SKILL_ROOT}/references/patch-prompt.md` for the prompt template. Substitute the finding's values and worktree path into the `${...}` placeholders.
-
-**Step 2b: Handle skipped findings**
-
-If the subagent returned `"status": "skipped"` (not `"applied"`), do NOT proceed to Steps 3-4. Instead:
-1. Record the finding in `data/patches.jsonl` with `"status": "error"` and `"error": "Subagent skipped: ${skipReason}"`
-2. Clean up the worktree
-3. Continue to the next finding
-
-**Step 3: Find reviewers**
-
-```bash
-uv run ${CLAUDE_SKILL_ROOT}/scripts/find_reviewers.py "${FILE_PATH}"
-```
-
-**Step 4: Create draft PR**
-
-```bash
-cd "${WORKTREE}" && git push -u origin HEAD:"${BRANCH}"
-```
-
-Create the PR with a 1-2 sentence "What" summary based on the finding and fix, followed by the finding description and verification reasoning:
-
-```bash
-REVIEWERS=""
-# If find_reviewers.py returned reviewers, build the flags
-# e.g., REVIEWERS="--reviewer user1 --reviewer user2"
-
-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}
-```
-
-Save the PR URL.
-
-**Step 5: Record and cleanup**
-
-Append to `data/patches.jsonl` (use `"created"` as status for successful PRs, not the subagent's `"applied"`):
-```json
-{"findingId": "...", "prUrl": "https://...", "branch": "...", "reviewers": ["user1", "user2"], "filesChanged": ["..."], "status": "created|existing|error"}
-```
-
-Remove the worktree:
-```bash
-cd "$(git rev-parse --show-toplevel)"
-git worktree remove "${WORKTREE}" --force
-```
-
-**Error handling**: On failure at any step, write to `data/patches.jsonl` with `"status": "error"` and `"error": "..."`, clean up the worktree, and continue to the next finding.
-
-Update manifest: set `phases.patch` to `"complete"`.
-
-**Report** to user after all patches:
-
-```
-## 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) |
-...
-```
-
----
-
-## Phase 5: Organize
-
-**Run** (1 tool call):
-
-```bash
-uv run ${CLAUDE_SKILL_ROOT}/scripts/organize.py ${SWEEP_DIR}
-```
-
-Parse the JSON stdout.
-
-**Report** to user:
-
-```
 ## Sweep Complete
 
 | Metric | Count |
@@ -356,45 +76,3 @@ Parse the JSON stdout.
 
 Full report: `{summaryPath}`
 ```
-
-**On failure**: Show the error and note which steps completed.
-
----
-
-## Resuming a Sweep
-
-Each phase is incremental. To resume from where you left off:
-
-1. Check `data/manifest.json` to see which phases are complete
-2. For scan: pass `--sweep-dir` to `scan.py`
-3. For verify: existing `data/verify/<id>.json` files are skipped
-4. For issue: `create_issue.py` is idempotent (skips if `issueUrl` in manifest)
-5. For patch: existing entries in `data/patches.jsonl` are skipped
-6. For organize: safe to re-run (idempotent)
-
-## Output Directory Structure
-
-```
-.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
-```

package/skills/warden-sweep/SOURCES.md

@@ -0,0 +1,43 @@
+# Warden Sweep Sources
+
+## Source Inventory
+
+| Source | Trust tier | Confidence | Usage constraints |
+|--------|------------|------------|-------------------|
+| `skills/warden-sweep/SKILL.md` | canonical runtime | high | Keep as router and phase overview. |
+| `skills/warden-sweep/references/*.md` | bundled runtime references | high | Keep focused by phase or lookup need. |
+| `skills/warden-sweep/scripts/*.py` | executable workflow | high | Script interfaces in references must match these files. |
+| `src/cli/output/jsonl.ts` | Warden output contract | high | Verify JSONL parsing assumptions when Warden output changes. |
+| `src/output/renderer.ts` and `src/types/` | finding/report semantics | high | Verify severity, confidence, and finding fields here. |
+| GitHub CLI commands used by scripts | external tool contract | medium | Confirm command flags when GitHub CLI behavior changes. |
+
+## Coverage Matrix
+
+| Dimension | Coverage status | Evidence |
+|-----------|-----------------|----------|
+| Workflow phases | covered | `SKILL.md` routes scan, verify, issue, patch, organize, and resume behavior to focused references. |
+| Script interfaces | covered | `references/script-interfaces.md` lists scripts, arguments, outputs, and side effects. |
+| Artifact schema | covered | `references/resume-and-artifacts.md` documents directories and key JSONL/JSON files. |
+| Verification behavior | covered | `references/verify-phase.md` and `references/verify-prompt.md` define qualification and rejection behavior. |
+| Patch behavior | covered | `references/patch-phase.md` and `references/patch-prompt.md` define triage, worktree isolation, draft PR creation, and cleanup. |
+| Known issues/workarounds | partial | Resume, partial scans, skipped findings, and existing PR dedup are covered; CI follow-up and rate-limit recovery are not. |
+| Version/migration variance | partial | Current artifact names and script interfaces are documented; no formal migration path exists for old sweep directories. |
+
+## Decisions
+
+- Split phase detail out of `SKILL.md` so agents load only the current phase instructions.
+- Keep script interface documentation separate from phase runbooks because scripts are reused across phases and by resume workflows.
+- Describe verification and patch work in host-neutral terms while allowing parallel agent tasks when the host supports them.
+- Keep prompt templates as separate references because they are substituted into delegated verification and patch work.
+- Keep generated sweep artifacts under `.warden/sweeps/<run-id>/` so runs are resumable and isolated from normal source files.
+
+## Open Gaps
+
+- Add a redacted fixture sweep to validate the full workflow without touching real GitHub repositories.
+- Document rate-limit and permission failure recovery if these become common in real sweeps.
+- Add migration notes if artifact schemas change after users have existing sweep directories.
+- Consider adding a script-level dry-run mode for issue and PR creation.
+
+## Changelog
+
+- 2026-04-27: Reverse-engineered maintenance spec and split the distributed `warden-sweep` workflow into phase references.

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