docs: align ClawSweeper comment prefilter

[vincentkoc]

No description provided.

[clawsweeper]

Codex review: needs changes before merge. Reviewed June 21, 2026, 6:23 AM ET / 10:23 UTC.

Summary
The branch modifies docs/target-dispatcher.md, carrying the merged rate-limit-safe dispatcher setup and adding a narrower comment-prefilter alias list with text that the router remains authoritative.

Reproducibility: not applicable. this is a docs-only PR rather than a bug report. Source inspection checked the documented command boundary against the command extractor and parser tests.

Review metrics: 2 noteworthy metrics.

• Changed surface: 1 docs file modified, 0 runtime files. The PR affects copy-paste dispatcher guidance, not code executed by this repository.
• GitHub merge state: CONFLICTING / DIRTY. Maintainers need a branch rebase or conflict repair before normal merge review can complete.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🌊 off-meta tidepool
Patch quality: 🦐 gold shrimp
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Rebase the branch onto current main so only the comment-prefilter docs delta remains.
• Run git diff --check after resolving the docs conflict.

Risk before merge

• [P1] GitHub reports the branch as conflicting/dirty, so it cannot merge until rebased or conflict-resolved against current main.
• [P1] Conflict resolution should preserve the already-merged dispatcher setup from docs: clarify rate-limit-safe dispatcher setup #344 and apply only the narrower prefilter docs delta on top.

Maintainer options:

1. Decide the mitigation before merge
   Rebase onto current main and land the narrow docs follow-up if maintainers agree, keeping the runtime router as the authoritative command grammar.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P2] A mechanical conflict repair is clear: rebase this branch onto current main and keep only the narrow docs prefilter follow-up.

Security
Cleared: Cleared: the diff is documentation-only and does not change executable workflows, dependency sources, permissions, secrets, or package scripts in this repository.

Review details

Best possible solution:

Rebase onto current main and land the narrow docs follow-up if maintainers agree, keeping the runtime router as the authoritative command grammar.

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

Not applicable; this is a docs-only PR rather than a bug report. Source inspection checked the documented command boundary against the command extractor and parser tests.

Is this the best way to solve the issue?

Yes; aligning the copy-paste dispatcher prefilter to the router's standalone alias boundary is narrow and maintainable, but the branch needs conflict resolution first.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add P3: This is low-risk dispatcher documentation cleanup with a mergeability blocker, not a runtime regression.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Label justifications:

• P3: This is low-risk dispatcher documentation cleanup with a mergeability blocker, not a runtime regression.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Evidence reviewed

Acceptance criteria:

• [P1] git diff --check.

What I checked:

• Repository policy read: AGENTS.md was read in full; its maintainer-authored non-closeable rule and docs/workflow review guidance apply to this PR. (AGENTS.md:1, f94c65a91f23)
• PR diff surface: The PR changes one documentation file and narrows the sample Pre-filter ClawSweeper comment regex while explaining the standalone aliases. (docs/target-dispatcher.md:93, bbdbfad74eed)
• Router grammar source: Current command extraction accepts standalone /auto merge, /autoclose, /review, and /clawsweeper ..., which matches the narrower docs direction. (src/repair/comment-command-text.ts:21, f94c65a91f23)
• Parser coverage: Existing tests cover /clawsweeper subcommands, standalone /review, standalone /automerge variants, and /autoclose, supporting the docs distinction between /clawsweeper ... and standalone aliases. (test/repair/comment-router-core.test.ts:148, f94c65a91f23)
• Mergeability check: GitHub reports this PR as mergeable: CONFLICTING and mergeStateStatus: DIRTY, likely because the branch still carries the already-merged dispatcher setup from docs: clarify rate-limit-safe dispatcher setup #344 as a distinct commit. (bbdbfad74eed)
• Related merged setup PR: docs: clarify rate-limit-safe dispatcher setup #344 merged the rate-limit-safe dispatcher setup that this branch also carries, leaving this PR as a follow-up plus rebase/conflict task rather than a clean one-commit docs delta. (docs/target-dispatcher.md:37, f94c65a91f23)

Likely related people:

• vincentkoc: Authored the merged dispatcher docs setup, the prior API-pressure work, and recent exact-queue/comment-routing changes used as source context for this PR. (role: recent area contributor; confidence: high; commits: f94c65a91f23, 1566ad6a0a5b, ac8f2c5e61c2; files: docs/target-dispatcher.md, src/repair/comment-webhook.ts, src/repair/comment-command-text.ts)
• Peter Steinberger: Established much of the current target dispatcher documentation in the release commit and made nearby exact-queue docs updates. (role: original and adjacent docs contributor; confidence: medium; commits: dc824915bb6c, 30163dfd667b; files: docs/target-dispatcher.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

• 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.