ClawSweeper Documentation

ClawSweeper is a conservative maintainer tool designed for one-cluster issue and PR cleanup. It operates as a separate 'repair lane' with stricter mutation gates than standard backlog sweepers.

Core Workflow:

1. Takes a curated GitHub issue/PR cluster.
2. Uses a Codex worker to classify items.
3. Applies narrow, auditable cleanup actions only when evidence is strong.

Allowed Automated Close Reasons:

• duplicate of a clear canonical thread
• superseded by a clear canonical thread
• fixed by a specific candidate fix

Scope & Security:

• Out of Scope: Security-sensitive reports. These are routed to central OpenClaw security handling.
• In Scope: Ordinary bugs, provider gaps, duplicate cleanup, and feature gaps (unless they represent a trust-boundary bypass).
• Manual Cleanup Policy: For drive-by PRs (e.g., blank templates, docs-only churn, test-only spam), you can opt-in to use the low-signal-prs.md instructions. This policy should return needs_human for plausible bug fixes or items with active maintainer signal.

ClawSweeper is a conservative maintenance bot designed for OpenClaw repositories. It automates the review of open issues and pull requests, manages GitHub comments, and can perform guarded repairs or automerge work based on trusted findings.

Key behaviors include:

• Reviewing: Scans issues and PRs on a schedule or via GitHub events.
• Reporting: Writes durable markdown reports and syncs a single, marker-backed public review comment per item.
• Command Routing: Responds to maintainer commands like @clawsweeper review, @clawsweeper fix, @clawsweeper autofix, and @clawsweeper automerge.
• Repairing: Repairs opted-in PRs using a bounded Codex review/fix loop.
• Implementing: Automatically opens guarded implementation PRs for high-confidence bug fixes if configured.

Note: The OpenClaw-hosted instance is not a public service. To use ClawSweeper for your own project, you must fork the repository, deploy it in your own organization, and configure it for your repositories.

The Live Dashboard provides a high-level view of the ClawSweeper pipeline. Key observability metrics include:

• Active Pipeline Rows: Grouped by automerge, repair, exact review, hot review, apply, or background review.
• Codex Jobs: Real-time tracking of active Codex jobs, including current GitHub Actions step, elapsed time, target, lane, and step timeline.
• Operational Health:
  • Queued runs: Marked as degraded after 30 minutes.
  • In-progress runs: Marked as stalled after 150 minutes.
• Automatic Builds: A five-stage overview (intake through results) grouped by source issue, showing lifecycle stages like queued, planning, building, completed, or blocked.
• Worker Reliability: Tracks error rates, recovery rates, and unresolved failures (including those hidden by continue-on-error).
• Automerge Telemetry: Samples failure rates, runtimes, and active/stalled attempts for the dedicated repair workflow.
• Apply Health: Reports on closure processing, durable review-comment sync, and skip-next-action buckets (e.g., stale reviews, missing close proof, protected labels).

OpenClaw Bay is an experimental, read-only visualization of the live ClawSweeper pipeline. It transforms active worker states into animated crustaceans moving across a shoreline.

Lane States

The visualization groups current worker states into five active lanes:

• Arriving
• Setting up
• Reviewing
• Repairing
• Applying

Behavior and Lifecycle

• Advancement: When an item advances, it raises a ready flag before the master sweeper moves it to the next lane.
• Retriggering: Any new run for the same GitHub item is represented by a 'tunnel'.
• Terminal States: Completed, failed, and cancelled items are moved to terminal pools.
• CHECKING State: If a worker disappears without explicit outcome evidence, it remains in its last lane with a CHECKING status for up to 150 seconds before being swept into a terminal pool.
• Tide Animation: The terminal buffer is small. At 20 proved outcomes, the tide animation clears the visible pools. The system retains the most recent 20 washed outcomes and at most 256 seen event identifiers.

For items that are kept open, you can mark them as potential manual work lanes for maintainers by setting the workCandidate field. This does not mutate GitHub; it only proposes a candidate for later promotion.

When to use queue_fix_pr: Set workCandidate to queue_fix_pr only if all the following are true:

1. The report is valid and not already closed/superseded by a merged fix.
2. The requested fix is narrow enough for one focused PR.
3. The affected area, likely files, and validation path are reasonably clear.
4. Related reports can be handled by a single canonical fix PR.
5. No security-sensitive, release-blocking, product-strategy, or broad architecture decisions are required first.

When to use manual_review: Set workCandidate to manual_review when the item requires human priority or product judgment before implementation.

When to use none: Set workCandidate to none for close decisions, stale/unclear reports, security-sensitive work, protected-label items, broad feature programs, pure administration, or items already paired with an open fix PR.

Required fields for queue_fix_pr:

• workPrompt: A concrete, custom maintainer prompt for the repair lane (include bug/feature, fix boundary, related refs, likely files, validation commands, and changelog expectations).
• workValidation: The exact tests or checks a fix PR should run.
• workLikelyFiles: Probable implementation/test/docs paths.

ClawSweeper reports use structured frontmatter to define the state and suitability of an issue for automated repair. These fields drive the dashboard visibility, coding plan generation, and GitHub label synchronization. Key fields include:

• item_category: The type of issue (e.g., security).
• reproduction_status & reproduction_confidence: Status of the bug reproduction and how certain the system is.
• requires_new_feature, requires_new_config_option, requires_product_decision: Boolean flags for blockers.
• vision_fit, vision_fit_evidence, implementation_complexity: Metadata regarding how well the fix aligns with project goals.
• auto_implementation_candidate: Options are none, strict_bug, or vision_fit.
• work_candidate: Options are none, manual_review, or queue_fix_pr.
• work_status: Options are none, manual_review, or candidate.
• work_priority & work_confidence: Priority and confidence levels for the work.
• work_cluster_refs, work_validation, work_likely_files: Contextual data for the repair process.

ClawSweeper rates PRs using internal tiers which are mapped to crustacean labels in public output. Ratings should focus on the quality of the evidence and the patch, not the contributor.

Internal Rating Scale (prRating)

• S: Exceptional (strong proof, clean implementation, no blockers).
• A: Clearly above average.
• B: Normal good/likely mergeable quality.
• C: Useful signal, but limited confidence.
• D: Thin proof, validation, or implementation signal.
• F: Not quality-ready (missing proof or serious correctness/safety concerns).
• NA: Non-PR or not-applicable.

Tiering Logic

• proofTier: Based on real behavior proof quality.
• patchTier: Based on implementation correctness, security, scope, and findings.
• overallTier: The weaker of the proofTier or patchTier.

Note: Real behavior proof is a merge gate. Missing or insufficient proof must cap or lower the overall rating.