docs: remove divider comments by steipete · Pull Request #88115 · openclaw/openclaw

steipete · 2026-05-29T19:19:06Z

Summary

Adds a broad inline-comment checkpoint across TS/TSX files so each file has a header describing its purpose.
Adds JSDoc-style inline docs for exported APIs in core/UI/package surfaces and extension api.ts / runtime-api.ts / setup-api.ts boundaries.
This is a WIP review checkpoint; follow-up work will continue tightening low-value generated wording and adding more hand-authored comments around tricky implementation paths.

Verification

Behavior addressed: comment and inline API documentation coverage only; no runtime behavior changes intended.
Real environment tested: local OpenClaw checkout on macOS, branch rebased onto origin/main at a39c2d784e.
Exact steps or command run after this patch: git diff --check origin/main...HEAD; repo-wide TS/TSX header scan; core/UI/packages export JSDoc scan; extension API-boundary export JSDoc scan; generated artifact net-diff scan.
Evidence after fix: header scan reported headerless_ts_tsx: 0; core/UI/packages export scan reported 0; extension API-boundary export scan reported 0; generated dist, node_modules, viewer runtime, and a2ui bundle net-diff scan was empty.
Observed result after fix: branch is rebased, working tree is clean, and generated artifacts are not part of the PR diff.
What was not tested: full build/test suite; this is a large comment-only WIP checkpoint.

Note: a local sanitized transcript candidate exists, but no transcript was added because explicit approval was not requested before opening this WIP PR.

clawsweeper · 2026-05-29T19:20:34Z

Codex review: needs changes before merge. Reviewed May 31, 2026, 3:59 AM ET / 07:59 UTC.

Summary
The branch adds or rewrites inline/JSDoc comments across Control UI, Android, service-worker, and related source files with no intended runtime behavior change.

Reproducibility: yes. for the review finding: the merge diff shows 18 removed locale markers while scripts/control-ui-i18n.ts still emits the same marker. I did not run pnpm ui:i18n:check because this review is read-only, but the source contract is enough to reproduce the drift.

Review metrics: 1 noteworthy metric.

Generated locale markers: 18 removed. These files are generated outputs, so marker drift is a concrete pre-merge automation concern rather than ordinary comment cleanup.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🐚 platinum hermit
Patch quality: 🦐 gold shrimp
Result: needs maintainer review before merge.

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

Rank-up moves:

Restore the locale generated markers or intentionally update the generator contract.
[P2] Run pnpm ui:i18n:check and the appropriate changed gate after the repair.

Risk before merge

[P1] Merging as-is leaves 18 generated locale bundles out of sync with scripts/control-ui-i18n.ts, so the i18n drift check or changed gate can fail until the marker is restored or the generator contract changes intentionally.
[P1] The PR body lists scan and diff proof but not a broad changed-check/Testbox run after the current head, which matters because this is a 190-file source sweep.

Maintainer options:

Restore generated ownership markers (recommended)
Put the exact generator-emitted marker back in every non-English locale bundle and verify no generated-marker removal remains before merge.
Change the generator contract intentionally
If maintainers want to remove the marker, update scripts/control-ui-i18n.ts, scoped generated-output guidance, and the i18n check expectations in the same branch.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Restore the exact `// Generated by scripts/control-ui-i18n.ts.` line in each non-English `ui/src/i18n/locales/*.ts` bundle removed by this PR, keep `scripts/control-ui-i18n.ts` unchanged, and verify no generated marker removal remains.

Next step before merge

[P2] A narrow automated repair can restore the generated locale markers; maintainers still own the final merge decision because the PR has the protected maintainer label.

Security
Cleared: The actual merge result is a comment/generated-output sweep and does not change dependencies, CI, secrets handling, package resolution, or code-execution policy.

Review findings

[P2] Restore generated locale headers — ui/src/i18n/locales/ar.ts:3

Review details

Best possible solution:

Restore the generated locale ownership markers, run the focused i18n drift check plus the appropriate changed gate, then let maintainers decide whether the broad comment sweep is worth merging.

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

Yes for the review finding: the merge diff shows 18 removed locale markers while scripts/control-ui-i18n.ts still emits the same marker. I did not run pnpm ui:i18n:check because this review is read-only, but the source contract is enough to reproduce the drift.

Is this the best way to solve the issue?

No, not yet. The maintainable path is to keep generated locale bundles aligned with their generator, then review the remaining comment-only sweep on its merits.

Full review comments:

[P2] Restore generated locale headers — ui/src/i18n/locales/ar.ts:3
The merge result removes // Generated by scripts/control-ui-i18n.ts. from every non-English locale bundle while renderLocaleModule still emits that line and ui/AGENTS.md treats these bundles as generated output. That leaves committed generated files out of sync with their generator, so pnpm ui:i18n:check or changed gates will report drift; keep the marker or change the generator/check contract intentionally.
Confidence: 0.93

Overall correctness: patch is incorrect
Overall confidence: 0.86

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against b48c72cd198b.

Label changes

Label changes:

add merge-risk: 🚨 automation: The merge result desynchronizes generated locale bundles from their generator, which can break i18n drift or changed-check automation after merge.
add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🐚 platinum hermit and patch quality is 🦐 gold shrimp.
add status: 🛠️ actively grinding: The PR author has acted after the latest ClawSweeper review and work remains. Sufficient (live_output): The PR body includes structured after-change scan and git diff --check proof for the intended comment-coverage work, though that proof does not clear the generated-output finding.
remove rating: 🧂 unranked krab: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.
remove merge-risk: 🚨 compatibility: Current PR review merge-risk labels are merge-risk: 🚨 automation.
remove status: ⏳ waiting on author: Current PR status label is status: 🛠️ actively grinding.

Label justifications:

P2: This is a normal-priority cleanup PR with a limited but concrete generated-output blocker.
merge-risk: 🚨 automation: The merge result desynchronizes generated locale bundles from their generator, which can break i18n drift or changed-check automation after merge.
rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🐚 platinum hermit and patch quality is 🦐 gold shrimp.
status: 🛠️ actively grinding: The PR author has acted after the latest ClawSweeper review and work remains. Sufficient (live_output): The PR body includes structured after-change scan and git diff --check proof for the intended comment-coverage work, though that proof does not clear the generated-output finding.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes structured after-change scan and git diff --check proof for the intended comment-coverage work, though that proof does not clear the generated-output finding.

Evidence reviewed

Acceptance criteria:

[P1] git diff --unified=0 origin/main...HEAD -- ui/src/i18n/locales scripts/control-ui-i18n.ts | rg '^-// Generated by scripts/control-ui-i18n' # expect no output.
[P1] pnpm ui:i18n:check.
[P1] git diff --check origin/main...HEAD.
[P1] node scripts/crabbox-wrapper.mjs run openclaw-pr-88115-check --shell -- "pnpm check:changed".

What I checked:

Protected-label gate: The provided live GitHub context lists the maintainer label, so this PR is not eligible for conservative cleanup closure even if it is mechanically repairable.
Actual merge result inspected: The GitHub merge commit has current main and the PR head as parents, and the diff from current main to the merge result is the 190-file comment sweep under review. (b021dd2a09d7)
Generated locale marker removed: The merge result removes the generated-file marker from 18 non-English locale bundles; ui/src/i18n/locales/ar.ts is representative and now starts exports at line 3 without the marker. (ui/src/i18n/locales/ar.ts:3, b021dd2a09d7)
Generator still emits marker: renderLocaleModule still emits // Generated by scripts/control-ui-i18n.ts., so the checked-in locale bundles no longer match the generator output. (scripts/control-ui-i18n.ts:487, b021dd2a09d7)
Scoped generated-output policy: The UI scoped guide says foreign-language locale bundles are generated output and should not be hand-edited unless a targeted generated-output fix is requested. (ui/AGENTS.md:7, b021dd2a09d7)
Whitespace sanity check: The merge result has no git diff --check whitespace errors, so the blocker is generated-output drift rather than diff formatting. (b021dd2a09d7)

Likely related people:

Peter Steinberger: Git blame points the UI generated-output guide and locale generator marker to current-main history authored by Peter Steinberger, and the PR head is the same broad comment sweep surface. (role: recent generated-i18n and comment-sweep contributor; confidence: medium; commits: 33c44626d211, b951dd9534e7; files: ui/AGENTS.md, scripts/control-ui-i18n.ts, ui/src/i18n/locales/*.ts)

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.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f40727e0f4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-31T06:24:12Z

 export {
  formatInboundEnvelope,
  resolveEnvelopeFormatOptions,


Restore deprecated SDK subpath markers

For third-party plugins that still import this compatibility subpath, removing the @deprecated JSDoc drops the only SDK-level warning and migration target that pointed callers to openclaw/plugin-sdk/channel-inbound; the same pattern appears on other src/plugin-sdk/* compatibility re-export files in this commit. This conflicts with the public-SDK deprecation guidance in src/plugin-sdk/AGENTS.md (public third-party API needs named compat/deprecation and migration direction) and makes these shipped shims look like current entrypoints again.

Useful? React with 👍 / 👎.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6837996156

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-31T06:37:13Z

+          (normalizedQuery !== undefined &&
+            normalizeProposalSearchText(lower).includes(normalizedQuery))


Avoid matching every proposal for punctuation-only queries

When the proposal query contains only characters stripped by normalizeProposalSearchText (for example "!!!" or "---"), query is truthy but normalizedQuery becomes ""; after this change the second branch runs, and every normalized proposal field satisfies .includes(""), so list_proposals returns all proposals instead of filtering. Keep the previous truthiness guard or otherwise skip the normalized comparison when it is empty.

Useful? React with 👍 / 👎.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5eeedb50c3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-31T07:44:46Z

+      return Object.assign({}, record, {
        openclawLeaseId: lease.leaseId,
        openclawGatewayInstanceId: lease.gatewayInstanceId,
      } as unknown as AcpLoadedSessionRecord;


Restore the missing Object.assign closing parens

In the ACPX runtime, replacing the object spread with Object.assign left this call unclosed, and the same pattern appears in the recordToSave assignment below. Any build or import that parses this plugin will fail with a syntax error before ACPX can run; close the Object.assign call or revert to the previous spread shape.

Useful? React with 👍 / 👎.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b951dd9534

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-31T07:56:16Z

 import type { TranslationMap } from "../lib/types.ts";

-// Generated by scripts/control-ui-i18n.ts.
 export const ar: TranslationMap = {


Restore generated locale headers

This line now omits the generated-file marker from every non-English locale bundle, but scripts/control-ui-i18n.ts still renders // Generated by scripts/control-ui-i18n.ts. in renderLocaleModule and pnpm ui:i18n:check treats any exact-output drift as dirty. Because these files are generated output under ui/AGENTS.md, this change will make the locale drift gate fail until the marker is restored or the generator is intentionally changed.

Useful? React with 👍 / 👎.

steipete · 2026-05-31T08:03:16Z

Verification before merge:

local: git diff --check
CI: Scan changed paths (precise), actionlint, no-tabs, security-fast, dependency-guard, Opengrep OSS, android-build-play, android-test-play, android-test-third-party, Real behavior proof, and ci-timings-summary passed on 225287cd0569b20fe318845d8a5555c63b5280e1
skipped by path selection: UI/build/docs/node lanes not touched by final diff

Known proof gaps: none for this comment-only Android cleanup.

steipete force-pushed the codex/inline-comments-wip branch from 70c544b to 31c0be0 Compare May 29, 2026 20:18

clawsweeper Bot added the P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. label May 29, 2026

BradGroux mentioned this pull request May 30, 2026

WORKING: All Microsoft Issues and PRs (refresh) #74163

Draft

chatgpt-codex-connector Bot reviewed May 31, 2026

View reviewed changes

docs: remove divider comments

225287c

steipete mentioned this pull request May 31, 2026

docs: clarify Android token comments #88554

Merged

clawsweeper Bot mentioned this pull request Jun 30, 2026

docs: document agent helper comments #88713

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

docs: remove divider comments#88115

docs: remove divider comments#88115
steipete merged 1 commit into
mainfrom
codex/inline-comments-wip

steipete commented May 29, 2026

Uh oh!

clawsweeper Bot commented May 29, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Uh oh!

steipete commented May 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		(normalizedQuery !== undefined &&
		normalizeProposalSearchText(lower).includes(normalizedQuery))

Uh oh!

Uh oh!

Conversation

steipete commented May 29, 2026

Summary

Verification

Uh oh!

clawsweeper Bot commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 31, 2026

Choose a reason for hiding this comment

Uh oh!

steipete commented May 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

clawsweeper Bot commented May 29, 2026 •

edited

Loading