fix(review): keep trailing markers within their HTML comments

[dwin-gharibi]

Fixes #1069.

An earlier HTML comment followed by visible prose ending in --> could be returned as one malformed trailing comment. Require the opener's first closing delimiter to match the candidate's closing delimiter. Marker recovery stops at intervening prose while retaining valid contiguous trailing markers.

This rewrites the original proposal on current main, preserving @dwin-gharibi's commit ancestry and credit. The final change is 23 added lines across three files: the guard, one focused regression, and the active documentation contract. The historical proof-only scaffold is removed from the proposed tree.

OpenClaw Bay impact: no observer API, UI, schema, route, or control change. Current production verdict normalization already retains visible prose and markers; this patch fixes marker parsing and does not add a body-stripping path. No changelog or dependency change.

Controlled real behavior proof

Base 7cc443fe363386e197a0b19fde0c4b534df6c943 and candidate 8d583a05915f737926cd54e8943aee471e2d35ac were built and exercised on macOS / Node 24.20.0. The actual built parser, review-state marker consumer, and durable verdict normalizer received synthetic comment strings. The proof was replayed after committing; the compiled parser SHA-256 is 66b36a3f2a8733dd343ac392645e884c4125492f2a612c105baba4ad605d5fd2.

Input	Before	After
Earlier closed comment + visible prose ending --> + two valid markers	Parser returns the earlier comment and prose as a third malformed comment	Parser returns only the two real markers
Two contiguous trailing markers	Both recovered; consumer reads sha=head	Same
Unterminated opener or stray closing delimiter	No trailing comments	Same
Durable verdict normalization	Visible prose retained	Same

Minimal reproduction of the changed production parser after pnpm run build:

import assert from 'node:assert/strict';
import { trailingHtmlComments } from './dist/review-comment-markers.js';
const markers = ['<!-- clawsweeper-verdict:needs-human item=321 sha=head -->', '<!-- clawsweeper-review item=321 -->'];
const input = ['<!-- earlier -->', 'Visible review details plan --> review -->', ...markers].join('\n');
assert.deepEqual(trailingHtmlComments(input), markers);
console.log(trailingHtmlComments(input));

This is controlled execution of compiled production functions, with no network or GitHub mutation. It proves the parser/consumer boundary, not a confirmed production incident or a live publishing workflow.

Validation

The regression fails on the base (3 pass / 1 fail), then 75 focused tests pass with the guard. Build, formatting, lint, static checks, and 13 changed-coverage tests passed. Managed Codex reviews before commit and on the committed branch both found no accepted/actionable P0 findings.

The local full pnpm run check was stopped after 7m07s without recent output. Buffered output revealed failures in two untouched fixtures: managed-scanner symlink handling and pinned Codex-source setup (EDITOR unset). Their causes were not established; local full-suite success is not claimed. Current-head hosted CI is required before landing.

[Copilot]

Pull request overview

Fixes trailingHtmlComments so it can’t fabricate a “comment” that spans visible prose when a stray --> appears outside of an actual HTML comment, ensuring durable ClawSweeper markers remain safely recoverable from published review bodies.

Changes:

• Harden trailingHtmlComments by rejecting backward-paired <!-- ... --> candidates unless the opener’s first --> is the terminator being matched.
• Add targeted regression/property tests covering the stray-terminator-in-prose case and a realistic mid-body review-history marker layout.
• Add a Crabbox/Node 24 proof contract + scripts under docs/proof/ to demonstrate well-formedness, boundedness, and no-loss behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/review-comment-markers.ts	Adds an interior-terminator guard so backward pairing can’t bridge across prose.
test/review-comment-markers.test.ts	Adds regression and property-guard tests for well-formed trailing comment extraction.
docs/proof/trailing-html-comment-parsing/run-proof.sh	Container proof runner that builds, compiles a pre-fix baseline, and runs proof + focused tests.
docs/proof/trailing-html-comment-parsing/run-proof.mjs	Proof script asserting well-formed, bounded, and no-loss claims against dist/.
docs/proof/trailing-html-comment-parsing/README.md	Documents the proof contract, claims, fixtures, and expected outputs.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed September 1, 2026, 5:08 AM ET / 09:08 UTC.

ClawSweeper review

What this changes

The branch prevents trailing review markers from being parsed across visible prose containing a closing HTML-comment delimiter, with a focused regression test and contract documentation.

Merge readiness

⚠️ Ready for maintainer review - 1 item remains

Keep this PR open: current main still has the unguarded marker parser, while this PR’s final three-file delta adds the narrowly targeted delimiter check and regression coverage. The supplied current-head compiled-parser proof and successful hosted checks support normal maintainer review.

Priority: P3
Reviewed head: 8d583a05915f737926cd54e8943aee471e2d35ac

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A narrow, correct parser repair with targeted regression coverage and current-head compiled behavior evidence.
Proof confidence	🐚 platinum hermit (4/6)	Sufficient (terminal): The PR body ties head 8d583a0 to a controlled Node 24 run of the compiled production parser and its marker consumers; the stated after-fix result rejects the prose bridge while preserving valid contiguous markers. It is a parser-boundary proof, not a claim about live GitHub publishing.
Patch quality	🦞 diamond lobster (5/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (terminal): The PR body ties head 8d583a0 to a controlled Node 24 run of the compiled production parser and its marker consumers; the stated after-fix result rejects the prose bridge while preserving valid contiguous markers. It is a parser-boundary proof, not a claim about live GitHub publishing.
Evidence reviewed	6 items	Current main remains affected: Current main still finds the nearest opener and slices to the candidate suffix without verifying that the suffix is that opener’s first terminator, so the reported prose-bridging input remains possible. Narrow final PR delta: The final merge commit adds the first-terminator comparison to the parser, four documentation lines, and a 17-line regression test relative to its current-main parent. Regression covers the reported delimiter sequence: The added case places an earlier closed comment before visible prose ending in --> and verifies that only the two real trailing markers are returned.
Findings	None	None.
Security	None	None.

How this fits together

ClawSweeper stores durable review state in trailing HTML comments on published review comments. The trailing-marker parser feeds review-state and recovery consumers that synchronize and recover those results.

flowchart LR
A[Published review comment] --> B[Trailing marker parser]
B --> C[Contiguous marker block]
C --> D[Review state consumers]
D --> E[Comment sync and recovery]

Loading

Before merge

• Complete next step (P2) - No mechanical repair is indicated; the focused current-head change is ready for ordinary maintainer review.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Focused final delta	production +2, tests +17, docs +4 across 3 files	The behavioral change is confined to the shared parser and directly covered by one targeted case.

Root-cause cluster

Relationship: fixed_by_candidate
Canonical: #1069
Summary: This PR is the focused candidate fix for the parser defect documented in the linked issue.

Members:

• canonical: Trailing HTML comment parsing #1069 - The PR body formally links this issue, and its reproduction and requested first-terminator guard match the PR’s parser change and regression.
• adjacent_distinct: fix(review): hydrate the complete pinned source #1333 - That merged PR addresses review-source hydration exposed during this PR’s review, not trailing HTML-marker parsing.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Technical review

Best possible solution:

Land the focused parser guard and regression so durable review-marker recovery cannot treat visible prose as hidden marker content.

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

Yes, source provides a high-confidence path: current main’s unguarded parser can be given the documented earlier-comment, visible--->, trailing-marker string. This read-only review did not execute the test.

Is this the best way to solve the issue?

Yes. Requiring the candidate terminator to be the opener’s first terminator directly enforces the contiguous-comment contract without changing valid trailing marker blocks.

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• add proof: sufficient: Contributor real behavior proof is sufficient. The PR body ties head 8d583a0 to a controlled Node 24 run of the compiled production parser and its marker consumers; the stated after-fix result rejects the prose bridge while preserving valid contiguous markers. It is a parser-boundary proof, not a claim about live GitHub publishing.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🦞 diamond lobster.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body ties head 8d583a0 to a controlled Node 24 run of the compiled production parser and its marker consumers; the stated after-fix result rejects the prose bridge while preserving valid contiguous markers. It is a parser-boundary proof, not a claim about live GitHub publishing.
• remove status: 📣 needs proof: Current PR status label is status: 👀 ready for maintainer look.
• remove merge-risk: 🚨 automation: Current PR review selected no merge-risk labels.
• remove merge-risk: 🚨 security-boundary: Current PR review selected no merge-risk labels.
• remove rating: 🦪 silver shellfish: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.

Label justifications:

• P3: This is low-blast-radius hardening of internal review-marker parsing, with no demonstrated user-facing outage.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body ties head 8d583a0 to a controlled Node 24 run of the compiled production parser and its marker consumers; the stated after-fix result rejects the prose bridge while preserving valid contiguous markers. It is a parser-boundary proof, not a claim about live GitHub publishing.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body ties head 8d583a0 to a controlled Node 24 run of the compiled production parser and its marker consumers; the stated after-fix result rejects the prose bridge while preserving valid contiguous markers. It is a parser-boundary proof, not a claim about live GitHub publishing.

Evidence

What I checked:

• Current main remains affected: Current main still finds the nearest opener and slices to the candidate suffix without verifying that the suffix is that opener’s first terminator, so the reported prose-bridging input remains possible. (src/review-comment-markers.ts:12, 1d79ae6c9f2d)
• Narrow final PR delta: The final merge commit adds the first-terminator comparison to the parser, four documentation lines, and a 17-line regression test relative to its current-main parent. (src/review-comment-markers.ts:13, 8d583a05915f)
• Regression covers the reported delimiter sequence: The added case places an earlier closed comment before visible prose ending in --> and verifies that only the two real trailing markers are returned. (test/review-comment-markers.test.ts:30, 8d583a05915f)
• Consumers use the parsed trailing block: Review-state parsing passes the text before the durable identity marker through the shared parser before extracting verdict and version metadata. (src/clawsweeper-review-comment-state.ts:340, 8d583a05915f)
• Feature history: History identifies the earlier current-main marker-tail implementation and the contributor’s original branch fix; the final merge commit carries the focused guard on top of current main. (src/review-comment-markers.ts:1, 3cad3486cbf2)
• Current-head behavior proof: The PR body records a controlled macOS/Node 24 run against head 8d583a0 using the compiled production parser and its consumers, with the malformed bridge excluded while contiguous markers remain recovered; the supplied hosted checks are successful. (8d583a05915f)

Likely related people:

• brokemac79: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• steipete: 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 (26 earlier review cycles; latest 8 shown)

• reviewed 2026-08-09T21:04:19.322Z sha 84f12f1 :: needs real behavior proof before merge. :: [P2] Keep fallback provisioning out of the synced checkout
• reviewed 2026-08-09T22:50:08.684Z sha 84f12f1 :: needs real behavior proof before merge. :: [P2] Provision fallback dependencies outside the synced checkout
• reviewed 2026-08-11T12:13:37.465Z sha 84f12f1 :: needs real behavior proof before merge. :: [P2] Provision fallback dependencies outside the synced checkout
• reviewed 2026-08-12T06:24:16.132Z sha 84f12f1 :: needs real behavior proof before merge. :: [P2] Provision proof dependencies outside the synced checkout
• reviewed 2026-08-12T11:58:17.636Z sha 61cfcbf :: needs maintainer review before merge. :: none
• reviewed 2026-08-12T13:02:42.603Z sha 40dcf94 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-12T23:32:40.990Z sha 40dcf94 :: needs real behavior proof before merge. :: [P2] Pass and verify the tested head in the Crabbox command | [P2] Stop overwriting the committed pre-fix fixture before proof
• reviewed 2026-08-19T06:14:10.688Z sha 07f5432 :: needs real behavior proof before merge. :: [P2] Stage the pre-fix fixture before the documented Crabbox run

[steipete]

@clawsweeper re-review

[clawsweeper]

🦞👀
Exact review queued.

Re-review progress:

• State: Failed
• Detail: The exact review could not verify the complete source. The durable queue will not retry this unchanged revision.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/33479764028
• Updated: 2026-09-01T06:57:35.213Z

[steipete]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
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: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/33490895040
• Updated: 2026-09-01T09:11:34.666Z