ClawSweeper documentation

• Status: active documentation index
• Owner: ClawSweeper maintainers
• Source of truth: the linked repository files and their owning code,

configuration, workflows, and tests

• Last verified: openclaw/clawsweeper@647503ec44b8e777dd172adf974a945367da0d19
• Update when: a document is added, retired, moved, changes lifecycle, or gains a

new canonical owner

ClawSweeper reviews GitHub issues and pull requests, publishes durable results, and applies or repairs only through guarded maintainer-controlled paths. Start with the task or audience below; this page is a map, not another operator manual.

#Start here

Production mutation commands are intentionally not repeated here. Follow the linked runbook, confirm its status and source of truth, and keep deployment, queue, and apply gates closed unless the current operator has explicit authority.

#Document lifecycle

Every evergreen page belongs to one of these states:

• active: current guidance for a supported surface
• proposed: a future design or runbook that grants no execution approval
• compatibility-only: retained for still-readable state or a supported

migration boundary, but not for creating new work

• historical: completed proof or decision history, not current procedure

Active runbooks and volatile configuration references should begin with status, role owner, owning source, last-verified revision, and update triggers. “Owner” is a responsibility role until maintainers approve a stable GitHub CODEOWNERS individual or team. Generated or checked values should name their checker; everything else requires human comparison with current main.

#Concepts and architecture

• Project vision — active; product goals and boundaries
• Orchestration — active; planner, review, publish, apply,

and repair shape

• Scheduler — active and volatile; scheduled and exact-event

execution behavior

• State storage — active; Worker, R2, and Git-backed state

ownership

• Canonical body tiering — proposed; preserve records

while moving exact bodies from SQLite to the existing R2 bucket

• Action ledger — active; mutation receipts and replay

boundaries

• Issue review advisory labels — active; structured review labels
• Review cache — active; reusable review-state contract
• Intake triage — active; bounded preliminary classification
• Local review preflight summary — proposed

local-range export; bounded advisory PR-body handoff and review-content reader

• GitHub webhook read model — active; signed

ingress, App subscriptions, snapshot freshness, and safety boundary

• Review authority contract — proposed integration;

inert role classifier and API evidence requirements

#Configuration and repository onboarding

• Automation limits — active; validated by

pnpm run check:limits

• Target repositories — active; profiles, generic

fallbacks, inventory, and apply membership

• Target dispatcher — active; exact-event integration
• OpenClaw event hooks — active; event routes
• Local branch review — active local/GitHub-isolated

replacement for hosted commit review

#Operations and runbooks

• Live dashboard — active; public observer surface and

operator diagnostics

• Queue-service split runbook — proposed;

unapproved production migration plan

• Local ClawSweeper skill — active; read-only

local exact-item or committed-range review

#Dashboards and observability

• Live dashboard — active; Worker status and operational

telemetry

• Agent performance metrics — execution timing, repeated work, chart ownership and observation limits
• GitHub publication egress telemetry — active;

wire denominator, credential attribution, completeness, and retention

• Triage dashboard — active; cached issue triage
• PR proof triage — active; maintainer proof

inspection

#Contributor, review, and proof guidance

• Contributing — active; setup, scope, PR evidence, and

author-owned review loop

• Agent instructions — active and binding for coding agents
• Changelog fragments — active; one-bullet

ClawSweeper release-note fragments and the release-time stitch

• PR review comments — active; review-thread handling
• Related issue discovery — active; duplicate and

adjacent-report context

docs/proof/** contains inspectable artifacts for specific changes. Those files support their recorded claim but do not override current runbooks.

#Proof media retention

Commit lightweight, diffable proof records: the claim and limits, exact source or head SHA, reproduction command, provider/image/lease provenance, fixture hashes, observable assertions, and compact normalized JSON. Full-resolution screenshots, videos, and traces may be committed while a pull request is under review, but prune them from main after merge once the durable review and proof record exist; git history retains the review-time bytes.

Keep a heavy binary only when an active canonical document embeds or links it, or when runtime or test tooling consumes it. Prefer one current compressed poster or WebP over accumulated before/after sets.

#Close policy

• Implemented-on-main paired close policy

— active policy and formal GitHub-link requirement

• Obsolescence policies — active policy map
• Unsponsored feature policy — active
• Product direction policy — active
• Material SQLite change discussion proposal

— proposed; maintainer decision required before any enforcement

• Author PR budget policy — active
• Stalled PR policies — active
• Oversized PR policy — active

#Security and special-purpose surfaces

• Security-sensitive work must use maintainer security handling rather than a

normal public PR or public documentation page.

#Update triggers

Review the relevant pages in the same change when any of these surfaces move:

• config/automation-limits.json or workflow limit literals: automation limits

and scheduler

• config/target-repositories.json, repository profiles, target inventory, or

apply membership: target-repository and dispatcher docs

• exact-review queue schema, retry classification, publication capacity,

batching, direct publication, or state writing: scheduler, limits, dashboard, and queue runbooks

• dashboard route, projection, or public-field changes: dashboard docs
• publication GitHub request paths, credential selection, or egress fields:

GitHub egress telemetry and public API docs

• mutation, close, proof, repair, or merge policy changes: policy pages,

CONTRIBUTING, AGENTS, and repair operations

• workflow retirement or replacement: every command example and compatibility

page that names the workflow

#Automated drift checks

pnpm run check:docs validates exact-case relative links and Markdown anchors, documented package scripts, workflow files, repository source paths, and the selected configuration-derived claims in config/documentation-sync.json. It runs through the existing static check and CI path. Add a manifest claim when volatile production configuration is quoted as a concrete value in prose. Stage newly added files before running the check so its repository inventory matches the proposed commit rather than unrelated untracked workspace contents. pnpm run check:changelog runs in the same static check and validates pending changelog.d/ fragments.

The check deliberately does not crawl external URLs, infer policy, assign ownership, or treat historical proof commands and paths as current contracts. The index, lifecycle labels, and whether a configuration claim should become policy remain human-reviewed.

The public documentation build reads config/documentation-site.json as its exhaustive lifecycle manifest. Active pages appear in navigation, search, the sitemap, and llms.txt. Proposed, historical, and proof pages remain available at stable generated paths for evidence links, but carry a visible lifecycle banner and noindex metadata and are excluded from canonical discovery. The documentation check fails when a page is unclassified or classified twice.