# AGENTS.MD

ClawSweeper is the conservative maintenance bot for OpenClaw repositories.
Keep changes narrow, evidence-backed, and automation-safe.

`AGENTS.md` is the canonical repository-wide coding-agent policy. Task-specific
workflows under `.agents/skills/` are opt-in procedures and do not override this
file. This repository does not currently maintain `AGENT.md`, `CLAUDE.md`, or
Cursor aliases; agents that do not discover `AGENTS.md` automatically must be
directed here rather than given a duplicated policy copy.

## Structure

- Main code: `src/clawsweeper.ts`.
- Repair lane code: `src/repair/`; canonical records live in the Cloudflare
  Worker, ledger/assets blobs live in R2, and remaining operational state lives
  in `openclaw/clawsweeper-state`.
- Tests: `test/*.test.ts` and `test/repair/*.test.ts`; add new coverage to the
  narrowest matching test file instead of growing `test/clawsweeper.test.ts`.
- Workflow: `.github/workflows/sweep.yml`.
- Vision and product boundaries: `VISION.md`.
- Explainer: `README.md`; state/dashboard repo: `../clawsweeper-state`.
- Changelog: one-bullet fragments in `changelog.d/`, stitched into
  `CHANGELOG.md` at release time; see
  [`changelog.d/README.md`](changelog.d/README.md).
- Open/reviewed records in the canonical Worker store:
  `records/<repo-slug>/items/<number>.md`.
- Archived records in the canonical Worker store:
  `records/<repo-slug>/closed/<number>.md`.
- Scratch/generated output: `.artifacts/`, `artifacts/`, `apply-report.json`.

Preserve one flat `items/` and `closed/` report layout per repository slug. Do
not split reports into issue/PR subtrees.

## Operating Model

- Review lane is proposal-only. It never closes GitHub items.
- Ordinary PRs receive one automatic completed review after ten quiet minutes.
  Later pushes, edits, reopen events, and scheduled passes require a new explicit
  review request. Failed or stale-source attempts can finish the first review.
  `clawsweeper:autofix` and `clawsweeper:automerge` no longer change review
  admission; they only keep their close protection.
- Maintainer-authored items and items labeled `maintainer` created from
  2026-10-15 03:50 UTC are reviewed like everyone else's: a PR gets its one
  automatic review. Older maintainer items need an explicit `@clawsweeper review`
  request.
  Finish the work and validation first; request review only when it is needed.
  Agents must not request reviews automatically or repeat a queued/running request.
  An explicit review request stays open while the queue requeues its own review
  after source drift, in place or from the publisher still holding the request's
  publication; that retry continues the request. A finished or replaced
  request, later changes after the answer, and scheduled passes need a new
  request.
- Apply lane mutates GitHub by syncing the durable Codex review comment and then
  closing only unchanged, high-confidence proposals.
- Repository-specific rules live in `src/repository-profiles.ts`; ClawHub apply
  may close only PRs that are certainly implemented on `main`.
- Hosted review concurrency and batching belong to the shared exact-review
  queue. Broad sweeps only admit candidates; they do not start per-run shards
  or grant immediate-apply authority.
- `openclaw/clawsweeper-state` is the live status surface and operational state
  store; the Worker/R2 pair is authoritative for records, ledger, and assets.
  Check current Actions and the canonical owner before trusting local generated
  timestamps.
- When asked about PRs outside `openclaw/clawsweeper`, treat the task as
  monitoring/debugging how ClawSweeper workflows operate on that PR. Do not fix
  foreign PR branches directly; ClawSweeper repair/automerge workflows own those
  branch edits.
- In `openclaw/openclaw`, `CHANGELOG.md` is release-owned. Do not ask contributor
  PR authors, repair workers, or automerge/autofix lanes to edit it during normal
  PR work. Preserve release-note context in PR bodies and commit messages instead.
- In `openclaw/clawsweeper` itself, record a user-visible change as one new
  `changelog.d/<pr-or-slug>.md` fragment holding a single bullet line. Do not
  edit `CHANGELOG.md` or other PRs' fragments in normal PR work; the release
  maintainer folds fragments in with `pnpm run changelog:stitch`, and
  `pnpm run check:changelog` validates them.
- When referencing GitHub issues or PRs in user-facing output, always include
  the full GitHub URL, not only `#12345`.

## Safety Rules

- Never disable or pause the live ClawSweeper sweep workflow unless Peter
  explicitly asks for that exact action.
- Do not run live apply/close commands unless Peter explicitly asks.
- For apply-path repros, copy one report into a temp `items/` dir and pass
  `--skip-dashboard`, `--item-number`, and a temp `--closed-dir`.
- Treat maintainer-authored and protected-label items as non-closeable, except
  for `implemented_on_main` with its existing
  source/history/release evidence and fresh apply guards (PRs additionally need
  GitHub-verified merged same-repository fixing provenance and paired-issue
  relationship checks; see `docs/implemented-on-main-close-policy.md`), and
  the maintainer-approved metadata-only `oversized_pull_request` policy:
  drafts, maintainer authorship, and the `maintainer` label do not exempt that
  reason. Its explicit PR exemption labels, `size: accepted-large`, other
  protected labels, live freshness checks, and apply gates still apply.
- Leave canonical OpenClaw Mantis locale PRs open; their generated-PR publisher
  owns freshness and auto-merge. See `docs/target-repositories.md` for identity scope.
- Snapshot or `updated_at` drift blocks apply unless the only change is the
  existing ClawSweeper review comment, or a ClawSweeper-recorded write for the
  item (`docs/scheduler.md`) while the complete source/timeline/head/activity
  receipt matches and no non-automation activity follows the review snapshot.
- Open-but-locked issues can exist when stale automation locked a closed issue
  and the author later reopened it. These must be skipped, not allowed to crash
  the apply run.
- Locked-comment 403s from GitHub are terminal apply skips, not retryable API
  failures.

## PR Validation and Landing

- For code-bearing changes, run focused validation that exercises the changed
  behavior, commit the final candidate, then obtain a fresh Codex review of the
  entire committed branch against a pinned intended base. Require a clean index
  and working tree; review the merge-base-to-HEAD range, not only the last commit.
  Complete this review before publication, handoff, or landing, including direct
  pushes where otherwise permitted. Early local review is optional feedback and
  does not replace this final branch review. See `CONTRIBUTING.md` for the command.
- Address every accepted or actionable finding and repeat the affected proof and
  review after fixes. A changed head, parent or selected base/range, dirty source,
  post-review hook edits, or changed review evidence, context, or applicable policy
  invalidates the affected review. Verify the final source after hooks and before
  publication or handoff. A failed or incomplete review never falls back to an
  earlier clean result; repeat review when needed, not merely to obtain a nicer
  verdict. An unchanged Git tree alone does not establish equivalent review inputs.
  CI, an older ClawSweeper comment, prior review comments, or manual self-review
  alone do not replace this loop or the separate gates below.
- At task kickoff, define the `pr-behavior-proof` contract for every
  code-bearing PR: claim, exercised surface, scenario or fixture, command and
  environment, observable result, artifact or trace, and limits. Run its
  controlled real-behavior proof before opening even a draft PR; only Martin
  may expressly approve an evidence-in-progress exception.
- Keep that proof current in the PR body. Tests, CI, mocks, snapshots, lint,
  typechecks, and clean review support the claim but never replace proof of a
  changed runtime, workflow, queue, API, UI, package, or integration path. On
  this Windows host, proof for those surfaces uses Docker-backed Crabbox
  `local-container` and records the current head, provider, image, lease,
  artifact, and limits. Use the narrowest meaningful proof first and broaden
  it for shared or higher-risk behavior. Docs-only changes normally need
  `git diff --check` and relevant link or command sanity instead.
- The public dashboard is observer-only: it may display status and provide
  view-only navigation to verified-public GitHub repository, item, workflow-run,
  and job pages. Those canonical GET links are references, not action controls.
  It never calls GitHub from the browser and never triggers or offers queue,
  workflow, GitHub, DLQ, recovery, deploy, rollback, or other mutation controls.
- A ClawSweeper result that requires proof or identifies an accepted/actionable
  finding remains PR-owner work, not a handoff. Before a manually requested
  review or re-review, put current proof and the finding disposition or evidence
  in the main PR body. A head or review-content body change after the durable review marker
  makes that review and any affected proof stale: rerun the affected proof and
  obtain a review for the current head and body. CI, labels, readiness, and
  maintainer permissions are evidence only; the explicit-user-approval boundary
  below still controls landing.
- Before merge or automerge, the latest ClawSweeper review must apply to the
  current PR head and review-content body. The canonical preflight reader excludes
  one valid advisory annotation only; human text, proof, and all outside whitespace
  remain review content. Raw event and concurrency guards can still invalidate
  after a metadata edit. Resolve every accepted finding. Apply each
  applicable `Rank-up moves:` item, or explicitly justify the exception in the
  PR body; Rank-up moves remain optional and do not by themselves block merge.
  Do not merge while proof is missing or while the review has an unresolved
  contributor-facing blocker.
- Land only after the current review and status evidence is ready for
  maintainer look, including `proof: sufficient` or `proof: override` when the
  proof label applies. This does not replace the user's explicit merge approval
  in the current conversation; agents must not merge or enable/execute
  automerge without it.

## Commands

```bash
corepack enable
pnpm install
pnpm run build
pnpm run test:unit
pnpm run format
pnpm run check
```

Use `pnpm run check` before handoff for code/test/workflow changes.

`engines.node` is `>=24`. Node 22 will install (no `engine-strict`) but the
notifier tests' 5-second retry paths surface as `cancelledByParent` under the
old `node:test` runner. Run on Node 24 or newer before reporting test
failures.

## GitHub Checks

Useful live probes:

```bash
gh run list --repo openclaw/clawsweeper --limit 20 --json databaseId,displayTitle,status,conclusion,createdAt,updatedAt
gh api repos/openclaw/clawsweeper/readme --jq '.content' | base64 --decode
gh api graphql -f query='query { repository(owner:"openclaw", name:"openclaw") { issues(states: OPEN) { totalCount } pullRequests(states: OPEN) { totalCount } } }'
```

For throughput/default tuning, start with `config/automation-limits.json` and
[`docs/limits.md`](docs/limits.md). `scripts/check-limits.ts` identifies the
derived docs, Worker values, and the `workflow_dispatch` literals that must stay
aligned. Effective exact-review admission, publication, and batching overrides
live in `dashboard/wrangler.toml`; owning fallback behavior lives in
`dashboard/exact-review-queue.ts`. Update `.github/workflows/sweep.yml` or
`src/clawsweeper.ts` only when the changed contract is actually owned there.

Use [`docs/README.md`](docs/README.md) for the documentation map, lifecycle
states, role ownership, and cross-surface update triggers.