docs: require fresh review before landing

[brokemac79]

Summary

Adds a root AGENTS.md PR Validation and Landing section for code-bearing ClawSweeper changes.

Problem

The repository had only a pnpm run check-before-handoff instruction. It did not tell agents to wait for a fresh current-head/body ClawSweeper review, keep real-behavior proof current, resolve accepted findings, or preserve explicit user approval before landing.

The CSW-072 audit found recent maintainer-account merges that bypassed the intended review wait: #939 and #901 merged after same-head ClawSweeper comments required proof before merge; #938, #937, #936, and #922 had no ClawSweeper comment. This is a policy gap, not proof of an autonomous merge actor.

Policy change

• Require focused validation and fresh Codex /review before commit and again against the branch base before landing.
• Require current real-behavior proof in the PR body; tests and CI remain supporting evidence.
• Require the latest ClawSweeper review to apply to the current PR head and body; accepted findings must be resolved.
• Require agents to apply or explicitly justify applicable Rank-up moves: while preserving their existing non-blocking semantics.
• Require ready-for-maintainer evidence and preserve the user's explicit merge-approval requirement.

Validation

• git fetch origin main --prune; rebased this one-commit branch onto current origin/main (6b3a2cef36f553b943c22502f05576e4a1f7616a).
• git diff --check origin/main...HEAD passed.
• Focused policy-contract probe compared the base and current root instructions: base had no PR Validation and Landing section; this head has the section and all six required clauses (fresh review before commit and against base, current PR-body proof, current head/body review, accepted findings, and explicit approval). git and codex review are available in the validation environment.
• codex review --uncommitted on the staged rebased patch: clean, no actionable findings.
• codex review --base origin/main on this final head: clean, no actionable findings.

Real Behavior Proof

• Claim: an agent reading the repository root instructions now receives explicit validation and no-land gates that were absent on the base revision.
• Surface: root AGENTS.md, the policy entrypoint agents read before repository work.
• Scenario / fixture: compare origin/main:AGENTS.md with this PR head and assert the new section plus its six mandatory clauses.
• Command / environment: PowerShell on the rebased branch; git diff --check origin/main...HEAD; a focused text-contract probe; codex review --uncommitted; codex review --base origin/main.
• Observed result: the base lacks the section; this head contains all six clauses; whitespace validation and both final Codex review passes are clean.
• Artifact / trace: head 59fdd05f98c6a158c1b6095493f20acf1746b6be; AGENTS.md.
• Limits: this is an instruction-policy change, not a technical enforcement control. It cannot prevent a direct maintainer merge or independently verify a conversational user approval. A protected required-status/ruleset enforcement follow-up remains intentionally out of scope.

Codex review closeout

The initial branch review found that treating Rank-up moves: as blockers contradicted the repository's existing optional semantics. The wording was corrected to require application or PR-body justification while keeping Rank-up moves non-blocking. The final dirty-patch and branch-against-base reviews reported no accepted/actionable findings.

Maintainer decision

The user explicitly approved merging this repository-wide documentation policy in the current conversation on 2026-07-29. That satisfies the sole ClawSweeper Rank-up moves: item: obtain maintainer confirmation that the policy scope is intended, without treating the optional improvement as a merge blocker.

Risks / rollout

No runtime, workflow, queue, labels, or merge-gate configuration changes. The new policy deliberately does not enable automerge or authorize a merge.

[brokemac79]

@clawsweeper review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Failed
• Detail: The exact review did not produce a publishable artifact. The durable queue will retry it.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/30474374117
• Updated: 2026-07-29T17:15:09.538Z

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 29, 2026, 1:08 PM ET / 17:08 UTC.

ClawSweeper review

What this changes

This PR adds a root AGENTS.md section requiring fresh focused validation, current real-behavior proof, a current-head/body ClawSweeper review, resolution of accepted findings, and explicit user approval before code-bearing changes land.

Merge readiness

⚠️ Ready for maintainer review - 5 items remain

This PR is a focused, internally consistent documentation-policy change with no concrete patch defect found. It should remain open for a maintainer decision because it establishes a repository-wide landing expectation for code-bearing agent work rather than fixing an established implementation bug.

Priority: P3
Reviewed head: 59fdd05f98c6a158c1b6095493f20acf1746b6be
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused documentation-policy patch with a clear stated scope and no concrete correctness finding; maintainer agreement on policy direction remains the merge decision.
Proof confidence	🌊 off-meta tidepool	Not applicable: This PR changes only repository instructions; its supplied base-versus-head policy-contract evidence is useful validation, while the external runtime-proof gate does not apply to docs-only changes.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This PR changes only repository instructions; its supplied base-versus-head policy-contract evidence is useful validation, while the external runtime-proof gate does not apply to docs-only changes.
Evidence reviewed	4 items	Proposed policy surface: The one-file PR adds 26 lines to root AGENTS.md, defining a validation-and-landing loop for code-bearing changes while retaining the existing instruction that agents must not merge without explicit user approval. Scope is documentation only: The PR changes one repository-policy file and contains no runtime, workflow, permission, dependency, queue, label, or merge-gate configuration change. Relevant repository policy: The current root policy already makes repository guidance authoritative for agents, requires pnpm run check before handoff for code/test/workflow changes, and preserves explicit user control over live merge/apply behavior; the proposed text extends that guidance rather than changing executable enforcement.
Findings	None	None.
Security	None	None.

How this fits together

Root AGENTS.md is the repository policy entrypoint read by coding agents before they change ClawSweeper. This change guides work from local validation through PR evidence and review freshness to a maintainer-ready landing decision; it does not alter the running Worker, repair lane, or GitHub workflow configuration.

flowchart LR
  A[Code-bearing change] --> B[Focused validation]
  B --> C[Current PR proof]
  C --> D[Fresh ClawSweeper review]
  D --> E[Resolve accepted findings]
  E --> F[Maintainer-ready evidence]
  F --> G[Explicit user approval]
  G --> H[Landing decision]

Loading

Decision needed

Question	Recommendation
Should ClawSweeper adopt this repository-wide agent policy requiring fresh Codex review and current real-behavior proof for code-bearing changes before agents present work for landing?	Adopt the documented review loop: Merge the policy as written, retaining its stated limit that it guides agents but does not authorize or technically enforce a merge.

Why: The patch is a policy choice about the expected developer and agent landing workflow; source review can confirm the wording, but only maintainers can decide whether that workflow should be mandatory across all code-bearing changes.

Before merge

• Add real behavior proof - Not applicable: This PR changes only repository instructions; its supplied base-versus-head policy-contract evidence is useful validation, while the external runtime-proof gate does not apply to docs-only changes.
• Resolve merge risk (P1) - The new wording creates a repository-wide expectation that code-bearing agent changes receive fresh Codex review and current proof before landing; maintainers should confirm that this is the intended policy scope, especially for environments where a local Codex review is unavailable.
• Resolve merge risk (P1) - The policy is documentation guidance rather than a protected-rule or required-status control, so it cannot itself prevent direct human merges or independently validate user approval.
• Complete next step (P2) - A maintainer must choose whether this repository-wide landing policy is desired; there is no narrow mechanical repair to dispatch.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Policy-only diff	1 file changed; 26 added, 0 removed	The change is narrowly confined to repository instructions and does not modify executable automation.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Adopt a concise agent-facing landing policy if maintainers want this review-and-proof discipline, while keeping the existing explicit-user-approval boundary and treating protected rules or required statuses as a separate enforcement decision.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Adopt a concise agent-facing landing policy if maintainers want this review-and-proof discipline, while keeping the existing explicit-user-approval boundary and treating protected rules or required statuses as a separate enforcement decision.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is an instruction-policy change, and the PR body supplies a direct base-versus-head text-contract check for the new section and clauses.

Is this the best way to solve the issue?

Unclear: the policy is a narrow way to document the requested review discipline, but maintainers must decide whether a repository-wide agent requirement is preferable to a narrower repair/automerge-only rule.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 6b3a2cef36f5.

Labels

Label changes:

• add P3: This is low-risk documentation and process guidance rather than a user-facing runtime regression or availability incident.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This PR changes only repository instructions; its supplied base-versus-head policy-contract evidence is useful validation, while the external runtime-proof gate does not apply to docs-only changes.

Label justifications:

• P3: This is low-risk documentation and process guidance rather than a user-facing runtime regression or availability incident.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This PR changes only repository instructions; its supplied base-versus-head policy-contract evidence is useful validation, while the external runtime-proof gate does not apply to docs-only changes.

Evidence

What I checked:

• Proposed policy surface: The one-file PR adds 26 lines to root AGENTS.md, defining a validation-and-landing loop for code-bearing changes while retaining the existing instruction that agents must not merge without explicit user approval. (AGENTS.md:66, 59fdd05f98c6)
• Scope is documentation only: The PR changes one repository-policy file and contains no runtime, workflow, permission, dependency, queue, label, or merge-gate configuration change. (AGENTS.md:66, 59fdd05f98c6)
• Relevant repository policy: The current root policy already makes repository guidance authoritative for agents, requires pnpm run check before handoff for code/test/workflow changes, and preserves explicit user control over live merge/apply behavior; the proposed text extends that guidance rather than changing executable enforcement. (AGENTS.md:1, 6b3a2cef36f5)
• Audit context: The PR body identifies recent merged review-lane work as the motivation and explicitly limits this change to agent instructions rather than claiming it can prevent direct maintainer merges or independently verify conversational approval. (AGENTS.md:66, 59fdd05f98c6)

Likely related people:

• steipete: The supplied related-item history identifies this contributor as the author of merged review-lane and workflow reliability work used as the PR's audit context, including the lease-finalization and state-hydration changes. (role: recent contributor to the review and workflow paths cited by the policy audit; confidence: low; commits: 10494a075761, e27b57429e48; files: AGENTS.md, .github/workflows/sweep.yml, src/clawsweeper.ts)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Obtain maintainer confirmation that the repository-wide policy scope is intended before landing.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[brokemac79]

@clawsweeper re-review