docs(mantis): correct proof publishing and QA dispatch guidance

[roboclaw-bot]

Related: openclaw/clawsweeper#1280

What Problem This Solves

Resolves a problem where maintainers following the Mantis guide are shown an evidence manifest the current publisher rejects and a ClawSweeper mention command that does not dispatch Mantis. The guide also leaves Telegram's separate QA entrypoint unclear, making it easy to mistake a published recording for verified behavioral proof.

Why This Change Was Made

Update the Mantis guide to match the existing implementation: schema-v2 lane expectations, manual Actions dispatch, and the separate Telegram QA/userbot path. Explain that an evidence manifest is not an authenticated proof receipt and that ClawSweeper—not Mantis publication—owns proof and readiness decisions.

This is a documentation-only correction, not a runtime dependency of command-triggered proof. The implementation is split between ClawSweeper #1425 (bare-command planning, automatic exact-head capture, sequential named checks, evidence verification, normal full review and conditional label publication) and OpenClaw #138953 (isolated named Web UI/Telegram execution and request-bound evidence). The proposed entrypoint is @clawsweeper proof, with optional explicit scenario lists and SHA. That command is distinct from the unsupported historical @clawsweeper mantis ... example corrected here. Both implementation PRs are now non-draft. @brokemac79 approved the coordinated full rollout on September 5, 2026: gated merges, compatible shared-broker and Worker deployment, protected producer pins and dedicated QA/Test Server validation. Hosted activation and acceptance remain in progress and are not claimed by this documentation correction; the implementation PRs retain their exact proof and rollout limits. This PR adds no command, receipt ingestion, workflow, or readiness automation; it is not a runtime dependency for that work. It does not restore automatic post-review proof retired in the related ClawSweeper PR, grant execution to read-only reviewers, or authorize merges.

User Impact

Maintainers get accurate instructions for the QA entrypoints available today and clearer limits on what their output proves:

• Use schema-v2 manifests with observed lane expectations; do not simply relabel the local runner's schema-v1 output.
• Use manual Mantis Actions dispatch instead of the unsupported mention-command example.
• Use the separate Telegram QA skill when independent user observations are needed, with explicit authorization, isolated execution, and leased test credentials.

There is no runtime behavior change. OpenClaw Bay is unaffected: no lifecycle, queue, telemetry, or dashboard contract changes.

Evidence

Checked the PR diff at 45fc88d13501d9906d59611344db8b3588acde8c: only docs/concepts/mantis.md changes. Source checks on September 4, 2026 confirm the concrete documentation mismatches:

Previous guidance	Owning implementation	Correction
Schema-v1 publication example	publish-pr-evidence.mjs requires v2 and boolean expectationMet values; a claimed pass is downgraded when expectations are unmet.	Show a v2 example and explain its trust limits.
No distinction between local and workflow manifests	run.runtime.ts still emits v1.	Document the incompatibility rather than claim it is fixed.
@clawsweeper mantis ... as a dispatch command	comment-router-core.ts falls back to freeform assistance for unrecognized mention commands.	Direct readers to existing manual Actions entrypoints.
Telegram routing unclear	mantis-scenario.yml has Discord, Slack, and web scenarios; the Telegram userbot skill owns the separate leased-user observation flow.	Explain the separate entrypoint, prerequisites, and authorization boundary.

Validation is source/documentation inspection, not an end-to-end QA run. No Mantis workflows, Telegram sessions, credential leases, or readiness transitions were exercised for this update. No runtime test result is claimed.

Worked on by

• @brokemac79

---

View the OpenClaw team session

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed September 5, 2026, 6:23 PM ET / 22:23 UTC.

ClawSweeper review

What this changes

Updates the Mantis QA guide with the accepted evidence format, manual workflow dispatch instructions, and the separate Telegram testing entrypoint.

Merge readiness

✅ Ready for maintainer review

The documentation correction remains useful: current main and the latest release retain the outdated examples. Source inspection supports the revised guidance, with no blocking findings; the separate proof-workflow rollout does not block this PR.

Priority: P3
Reviewed head: 45fc88d13501d9906d59611344db8b3588acde8c

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, source-supported documentation correction with no blocking findings.
Proof confidence	🌊 off-meta tidepool	Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Evidence reviewed	11 items	Introduced scope and whitespace validation: The pinned merge-base-to-head diff changes only docs/concepts/mantis.md. git diff --check passed; no production code, tests, workflows, dependencies, or machine-consumed frontmatter changed. Publisher contract matches the revised example: The complete publisher requires schema version 2, requires boolean expectationMet values for included lanes, and reconciles contradictory pass claims before publishing artifacts and comments. Local and workflow producers differ: The local runner still emits schemaVersion 1 at line 401. Discord and Slack workflow producers emit version 2 with lane expectations, and mantis-scenario.yml dispatches only the listed Discord, Slack, and web scenarios. The new text accurately documents this existing distinction.
Findings	None	None.
Security	None	None.

How this fits together

Mantis turns QA observations and recordings into published PR evidence. Its publisher validates the evidence manifest, while ClawSweeper independently evaluates proof and readiness.

flowchart TD
  A[Manual workflow dispatch] --> B[Mantis QA scenarios]
  B --> C[Observations and artifacts]
  C --> D[Evidence manifest validation]
  D --> E[Published PR evidence]
  E --> F[Independent ClawSweeper review]
  G[Separate Telegram QA entrypoint] --> C

Loading

Before merge

None.

Agent review details

Security

None.

PR surface

Docs +52. Total +52 across 1 file.

View PR surface stats

Area	Files	Added	Removed	Net
Source	0	0	0	0
Tests	0	0	0	0
Docs	1	64	12	+52
Config	0	0	0	0
Generated	0	0	0	0
Other	0	0	0	0
Total	1	64	12	+52

Review metrics

None.

Technical review

Best possible solution:

Keep the guide aligned with the existing publisher and QA entrypoints, with evidence publication clearly separated from execution authorization and readiness decisions.

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

Not applicable to this documentation-only patch; direct source inspection establishes the outdated manifest and dispatch examples without executing QA.

Is this the best way to solve the issue?

Yes. Correcting the existing guide is the appropriate scope; adding command dispatch or changing producer behavior would be separate implementation work.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 9dd869ec98eb.

Labels

Label justifications:

• P3: This is a bounded correction to maintainer QA documentation with no runtime behavior change.
• 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: Real behavior proof is not required because this PR only changes files under docs/.

Evidence

What I checked:

• Introduced scope and whitespace validation: The pinned merge-base-to-head diff changes only docs/concepts/mantis.md. git diff --check passed; no production code, tests, workflows, dependencies, or machine-consumed frontmatter changed. Public docs: docs/concepts/mantis.md. (docs/concepts/mantis.md:203, 45fc88d13501)
• Publisher contract matches the revised example: The complete publisher requires schema version 2, requires boolean expectationMet values for included lanes, and reconciles contradictory pass claims before publishing artifacts and comments. (scripts/mantis/publish-pr-evidence.mjs:186, 45fc88d13501)
• Local and workflow producers differ: The local runner still emits schemaVersion 1 at line 401. Discord and Slack workflow producers emit version 2 with lane expectations, and mantis-scenario.yml dispatches only the listed Discord, Slack, and web scenarios. The new text accurately documents this existing distinction. (extensions/qa-lab/src/mantis/run.runtime.ts:401, 45fc88d13501)
• Direct inspection of the dispatch dependency: The changed guide explicitly describes ClawSweeper command parsing, establishing the dependency signal. The inspected checkout's origin is openclaw/clawsweeper, and comment-router-core.ts matches its recorded HEAD: unknown mention commands become freeform_assist, with no typed Mantis command. No changed claim depends on the Codex runtime or protocol. (src/repair/comment-router-core.ts:2747, 03182ae34303)
• Telegram entrypoint and operational guidance: The Telegram QA adapter loads the repository userbot skill; its driver accepts message/edit events. The skill describes the broader recorder, leased credentials, fresh Gateway, and cleanup. The doctor source acquires a credential, starts the proxy, contacts Telegram, and releases the credential, supporting the warning that it is a live operation. (extensions/qa-lab/src/live-transports/telegram/userbot-skill.runtime.ts:99, 45fc88d13501)
• Existing contract coverage: The publisher test fixture uses schema v2 and lane expectations; the missing-boolean case asserts rejection through loadEvidenceManifest. Tests were inspected, not executed. (test/scripts/mantis-publish-pr-evidence.test.ts:89, 45fc88d13501)

Likely related people:

• Ayaan Zaidi: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

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.

History

Review history (5 earlier review cycles)

• reviewed 2026-09-04T11:13:47.584Z sha 45fc88d :: needs maintainer review before merge. :: none
• reviewed 2026-09-04T11:52:11.082Z sha 45fc88d :: blocked before merge. :: none
• reviewed 2026-09-05T10:47:10.401Z sha 45fc88d :: needs changes before merge. :: none
• reviewed 2026-09-05T17:44:27.594Z sha 45fc88d :: needs changes before merge. :: none
• reviewed 2026-09-05T18:06:24.379Z sha 45fc88d :: needs maintainer review before merge. :: none

[brokemac79]

Merged via squash.

• Prepared head SHA: 45fc88d13501d9906d59611344db8b3588acde8c
• Landed commit: 206aefe7e1a2c47989d8da92bf25ff8997ec00d3