Move OpenClaw-specific ClawSweeper review policy into AGENTS.md

Summary

Move OpenClaw-specific ClawSweeper review policy into root AGENTS.md so OpenClaw owns its repo-specific review rules and ClawSweeper can keep its generic review prompt focused on cross-repository mechanics.

This is the OpenClaw-side companion to openclaw/clawsweeper#185, which changes ClawSweeper to treat target AGENTS.md as repository policy and review evidence.

The new OpenClaw policy should be placed near the top of root AGENTS.md, preferably immediately after ## Start, so review agents encounter it before truncation, partial display, or skim-style reads can drop later sections.

Problem

openclaw/clawsweeper/prompts/review-item.md currently contains OpenClaw-specific policy mixed into the generic ClawSweeper review prompt.

That makes ClawSweeper less generic across repositories and creates two places where OpenClaw review policy can drift:

1. OpenClaw root AGENTS.md.
2. ClawSweeper's generic review prompt.

OpenClaw already has a root AGENTS.md with policy around architecture, docs, validation, GitHub/PR behavior, changelog expectations, plugin boundaries, compatibility, and testing. The OpenClaw-specific ClawSweeper review rules should live there.

Grounding

OpenClaw root AGENTS.md already covers repo policy that ClawSweeper should judge against, including:

• core stays plugin-agnostic;
• plugins cross into core through SDK, manifest metadata, injected runtime helpers, or documented barrels;
• owner-specific repair/detection/onboarding/auth/defaults/provider behavior belongs in owner plugins;
• public plugin SDK/API compatibility requires deprecation/compat metadata, docs, warnings when useful, and tests for old plus new;
• docs publish through docs.openclaw.ai;
• user-facing behavior changes need appropriate docs/changelog handling;
• validation depends on touched surface and should use the repo's listed commands;
• OpenClaw has repeated or sibling runtime surfaces where a one-sided fix can create regressions, including Codex/Pi-style runtimes, provider/model routing, channels, gateway/protocol paths, plugin SDK seams, and internal context-management paths;
• review policy should require ClawSweeper to check the blast radius of a proposed fix across sibling surfaces, not only the runtime, channel, provider, harness, plugin seam, or context path touched by the PR.

ClawSweeper's generic prompt currently embeds OpenClaw-specific review policy, including:

• clawhub close behavior for optional integrations, providers, channels, skill bundles, MCP work, and skill-only PRs;
• OpenClaw core lean/plugin ownership guardrails;
• OpenClaw changelog handling for user-facing fix, feat, and perf PRs;
• public docs-link preference for https://docs.openclaw.ai/...;
• OpenClaw-specific plugin API and provider/auth compatibility examples.

Those policies belong in OpenClaw AGENTS.md so ClawSweeper can judge OpenClaw items against target repo policy instead of hardcoding OpenClaw behavior inside its generic prompt.

Goal

Make root AGENTS.md the repository-owned source for OpenClaw-specific ClawSweeper review policy.

After this lands, a follow-up ClawSweeper cleanup can remove or shrink OpenClaw-specific paragraphs from prompts/review-item.md without losing review behavior.

Placement requirement

Add the new ClawSweeper Review Policy section near the top of root AGENTS.md.

Preferred location:

## Start
...
## ClawSweeper Review Policy
...
## Map
...

Do not bury this policy near the bottom of the file. Root AGENTS.md is long, and review agents should encounter the ClawSweeper policy before context truncation, partial display, or skim-style reads can drop later sections.

Full-read requirement

Root AGENTS.md should explicitly tell OpenClaw review agents, including ClawSweeper, to read the full root AGENTS.md before using it as review policy.

Partial reads are not enough for OpenClaw review decisions. Agents should not rely only on search snippets, the first matching section, head, local excerpts, partial line ranges, or a truncated copy. If context budget is a concern, the agent should still inspect the full file and then summarize or extract the relevant policy.

This matters because the new ClawSweeper Review Policy section is intended to replace OpenClaw-specific policy that currently lives in ClawSweeper's generic review prompt.

Proposed AGENTS.md addition

The proposed section below is a baseline. Adapt wording to match the existing terse root AGENTS.md style, but preserve the policy decisions and placement.

Add this section near the top of root AGENTS.md, preferably after ## Start:

## ClawSweeper Review Policy

ClawSweeper and other OpenClaw review agents must read this full root `AGENTS.md` before using it as review policy. Do not rely on partial reads, search snippets, `head`, local excerpts, partial line ranges, or truncated copies.

ClawSweeper reviews OpenClaw issues and PRs against this file as repository policy.

OpenClaw-specific review policy lives here, not in ClawSweeper's generic review prompt. ClawSweeper-owned schema, labels, close reasons, protected-label gates, maintainer-authored item gates, and mutation rules still live in `openclaw/clawsweeper`.

### Product boundary

- Core stays lean and plugin-agnostic.
- Optional integrations, providers, channels, skill bundles, MCP surfaces, and service-specific workflows should live in plugins, ClawHub, or owner repositories when current extension seams are sufficient.
- Keep OpenClaw core items open when the report identifies a missing core/plugin API, a bundled core regression, security/core hardening, or a product decision that maintainers need to make.
- For requests that can be satisfied outside core with current plugin, skill, MCP, or ClawHub surfaces, ClawSweeper may recommend the external/plugin path instead of core work.

### Skill and ClawHub routing

- Optional skill bundles and skill-only PRs should not be added to OpenClaw core by default.
- Skill-only work that can live outside core should be routed toward ClawHub or plugin/skill publication.
- Keep items open when the requested skill exposes a missing core extension API or a core bug.

### Compatibility and upgrade risk

- Plugin API changes are compatibility-sensitive.
- Provider routing, auth/session state, persisted preferences, config loading, migrations, setup workflows, startup checks, and fallback behavior are upgrade-sensitive.
- Changes that could break existing user config, remove fallback paths, fail closed, or require operator action should be treated as merge risk even when CI is green.
- Prefer preserving existing behavior by default plus adding explicit opt-in strict behavior when that avoids breaking current users.

### Blast radius and sibling-surface review

- Review whether a PR fixes the whole affected decision surface, not only the one runtime, provider, channel, harness, plugin seam, or context path touched by the diff.
- When behavior exists in sibling paths, check those paths before calling the fix complete. Examples include Codex/Pi-style runtimes, provider/model routing, channel delivery paths, gateway/protocol paths, plugin SDK seams, and internal context-management flows.
- Treat one-sided fixes as merge-risk when the same bug or behavior likely exists in another supported side.
- If a PR intentionally fixes only one side, the review should say what sibling surfaces were checked, why they are unaffected, or what follow-up issue/PR should cover them.

### Changelog review

- User-facing `fix`, `feat`, and `perf` changes need a `CHANGELOG.md` entry before landing.
- Contributor PR authors should not be blocked solely for missing changelog entries; changelog entries are maintainer-owned landing/release work.
- Do not request bot or maintainer handles in changelog thanks lines. Never require thanks for `@openclaw`, `@clawsweeper`, `@codex`, or bot authors.

### Docs links in public comments

- Public ClawSweeper comments should prefer `https://docs.openclaw.ai/...` links when the corresponding public docs page exists.
- Structured evidence can still cite repository files, lines, and SHAs for auditability.

### Validation expectations

- For OpenClaw code changes, judge validation against the touched surface, sibling surfaces with the same behavior, and the commands in this `AGENTS.md`.
- Validation should prove the fix on every affected side when practical. If only one side is validated, the review should name the unvalidated sibling surfaces and decide whether that is acceptable, merge-risk, or follow-up work.
- Real behavior proof matters for user-visible PRs. Unit tests, mocks, lint, typecheck, and CI are supplemental when the changed behavior needs runtime proof.
- Telegram-visible behavior should be demonstrated through the appropriate Telegram/Desktop proof path when a short visible proof can show the change.

Suggested follow-up in ClawSweeper

After this OpenClaw AGENTS.md update lands, a follow-up ClawSweeper PR can remove or shrink OpenClaw-specific sections from prompts/review-item.md.

Candidates to move out of the generic ClawSweeper prompt include:

• OpenClaw-specific clawhub routing details.
• OpenClaw-specific bundled skill guidance.
• OpenClaw-specific VISION.md guardrails around core staying lean and optional capability living in plugins/ClawHub.
• OpenClaw-specific changelog policy.
• OpenClaw-specific docs-link preference for docs.openclaw.ai.
• OpenClaw-specific plugin API and provider/auth compatibility examples, where they duplicate OpenClaw AGENTS.md.
• OpenClaw-specific blast-radius review rules for sibling runtimes, provider/model routing, channel delivery paths, plugin SDK seams, gateway/protocol paths, and internal context-management flows.

The generic ClawSweeper prompt should keep:

• output schema requirements;
• ClawSweeper-owned label taxonomy;
• close reason taxonomy;
• merge-risk label semantics;
• protected-label and maintainer-authored item gates;
• read-only review constraints;
• evidence requirements;
• generic PR review-finding rules;
• generic security and real-behavior-proof rules.

Non-goals

• Do not change ClawSweeper code in this OpenClaw issue.
• Do not add a new .clawsweeper.yml.
• Do not add a structured parser requirement.
• Do not require other repositories to update AGENTS.md.
• Do not change ClawSweeper labels, close reasons, schema fields, or merge-risk taxonomy.
• Do not broaden ClawSweeper auto-close authority.
• Do not place the new policy near the bottom of AGENTS.md.
• Do not rely on partial-file reads or section-only reads as sufficient review policy intake.

Acceptance criteria

• Root AGENTS.md contains an explicit ClawSweeper Review Policy section.
• The new section is placed near the top of root AGENTS.md, preferably immediately after ## Start.
• Root AGENTS.md explicitly tells ClawSweeper/review agents to read the full file before using it as review policy.
• The new section captures OpenClaw-specific policy currently embedded in openclaw/clawsweeper/prompts/review-item.md.
• The new section preserves OpenClaw's current repo policy: lean core, plugin/ClawHub ownership for optional capability, compatibility-sensitive plugin APIs, upgrade-safe defaults, sibling-surface blast-radius review, maintainer-owned changelog landing work, and public docs-link preference.
• The new section tells ClawSweeper to check blast radius across sibling OpenClaw surfaces, not only the runtime, provider, channel, harness, plugin seam, or context path touched by the PR.
• The policy covers one-sided fixes and requires the review to either verify sibling surfaces, explain why they are unaffected, or identify follow-up work.
• The change is docs/policy only in openclaw/openclaw.
• No ClawSweeper schema, labels, close reasons, or automation behavior changes are made in this issue.
• The issue enables a follow-up ClawSweeper cleanup PR to remove OpenClaw-specific paragraphs from the generic review prompt.

Validation

Docs/policy-only validation should be enough unless the final edit touches generated docs or scripts.

Suggested validation:

git diff --check AGENTS.md

If broader checks are desired, use the repository's normal docs/policy validation guidance from AGENTS.md.